@mesh-tech/mesh-cli 0.31.1 → 0.33.0

package/dist/bin/mesh.js

@@ -6912,7 +6912,7 @@ var init_src = __esm({
       z.object({ op: z.string().trim().min(1) }),
       z.object({ unavailable: z.string().trim().min(1) })
     ]);
-    apiSurfaceKindSchema = z.enum(["app", "vendor"]);
+    apiSurfaceKindSchema = z.enum(["app", "vendor", "events"]);
     apiDocsSiteAudienceSchema = z.discriminatedUnion("readers", [
       z.object({ readers: z.literal("partner"), roles: z.array(z.string().min(1)) }),
       z.object({ readers: z.literal("operator") })
@@ -11846,6 +11846,53 @@ function statedKind(decl, args) {
   if (decl.ctor === "VendorApiSurface") return "vendor";
   return /^["']([a-z]+)["']$/.exec(args.get("kind") ?? "")?.[1];
 }
+function programIdentities(text) {
+  const identities = [];
+  for (const d of surfaceDeclarations(text, RE_IDENTITY_NEW)) {
+    const options = optionsObject(d.body, text);
+    if (!options) continue;
+    const binding = [...text.matchAll(RE_IDENTITY_BINDING)].find(
+      (m) => text.indexOf(d.body, m.index) === m.index + m[0].length - 1
+    )?.[1];
+    identities.push({ binding, options: topLevelProperties(options) });
+  }
+  return identities;
+}
+function declaredProjectRoles(identity) {
+  const rolesText = identity.options.get("roles");
+  const coarseText = identity.options.get("coarseRoles");
+  if (rolesText !== void 0) return stringList(rolesText);
+  if (coarseText !== void 0) return stringList(coarseText);
+  return [];
+}
+function eventsRoleFindings(text) {
+  const findings = [];
+  const identities = programIdentities(text);
+  for (const decl of surfaceDeclarations(text, RE_EVENTS_NEW)) {
+    const options = optionsObject(decl.body, text);
+    if (!options) continue;
+    const args = topLevelProperties(options);
+    if (args.get("enabled") === "false") continue;
+    if (identities.length === 0) {
+      continue;
+    }
+    const identityText = objectLiteralOf(args.get("identity"), text);
+    const projectExpr = identityText ? topLevelProperties(identityText).get("projectId") : void 0;
+    const projectRoot = projectExpr ? /^([A-Za-z_$][\w$]*)\.projectId\b/.exec(projectExpr.trim())?.[1] : void 0;
+    const identity = (projectRoot ? identities.find((id) => id.binding === projectRoot) : void 0) ?? (identities.length === 1 ? identities[0] : void 0);
+    if (!identity) continue;
+    const declared = declaredProjectRoles(identity);
+    if (!declared) continue;
+    const missing = EVENTS_PROJECT_ROLES.filter((r) => !declared.includes(r));
+    if (missing.length === 0) continue;
+    findings.push({
+      code: "EVENTS_ROLES_UNDECLARED",
+      line: decl.line,
+      why: `mesh.apps.EventsService is declared but the app's ZitadelAppIdentity does not declare ${missing.map((r) => `"${r}"`).join(" or ")} \u2014 the events service authorizes bearer callers by these project roles, and a role the identity never declares cannot be granted from the Hub's Access tab, so no subscriber can be admitted`
+    });
+  }
+  return findings;
+}
 function docsAudienceUngrantable(text, decl, args, docs, httpText) {
   const findings = [];
   let roles;
@@ -11856,22 +11903,14 @@ function docsAudienceUngrantable(text, decl, args, docs, httpText) {
     roles = DEFAULT_PARTNER_DOCS_ROLES;
   }
   if (!roles || roles.length === 0) return findings;
-  const identities = [];
-  for (const d of surfaceDeclarations(text, RE_IDENTITY_NEW)) {
-    const options = optionsObject(d.body, text);
-    if (!options) continue;
-    const binding = [...text.matchAll(RE_IDENTITY_BINDING)].find((m) => text.indexOf(d.body, m.index) === m.index + m[0].length - 1)?.[1];
-    identities.push({ binding, options: topLevelProperties(options) });
-  }
+  const identities = programIdentities(text);
   if (identities.length === 0) return findings;
   const docsAuth = objectLiteralOf(docs.get("auth"), text);
   const clientExpr = (docsAuth ? topLevelProperties(docsAuth).get("clientId") : void 0) ?? (httpText ? topLevelProperties(objectLiteralOf(topLevelProperties(httpText).get("auth"), text) ?? "{}").get("clientId") : void 0);
   const clientRoot = clientExpr ? /^([A-Za-z_$][\w$]*)\.(?:clientIds|applications)\./.exec(clientExpr.trim())?.[1] : void 0;
   const identity = (clientRoot ? identities.find((id) => id.binding === clientRoot) : void 0) ?? (identities.length === 1 ? identities[0] : void 0);
   if (!identity) return findings;
-  const rolesText = identity.options.get("roles");
-  const coarseText = identity.options.get("coarseRoles");
-  const declared = rolesText !== void 0 ? stringList(rolesText) : coarseText !== void 0 ? stringList(coarseText) : [];
+  const declared = declaredProjectRoles(identity);
   if (declared) {
     for (const role of roles) {
       if (declared.includes(role)) continue;
@@ -11942,6 +11981,7 @@ function scanApp(root, appRel, resolution = probeResolution(root, appRel)) {
       hit("NO_REGISTER", indexRel, "never calls env.register({\u2026}) \u2014 the Hub cannot list this app");
     }
     for (const f of docsSiteFindings(readText(index))) hit(f.code, `${indexRel}:${f.line}`, f.why);
+    for (const f of eventsRoleFindings(readText(index))) hit(f.code, `${indexRel}:${f.line}`, f.why);
     for (const svc of serviceDirs(app)) {
       for (const f of srcFiles(svc)) {
         const text = readText(f);
@@ -12103,7 +12143,7 @@ function registerAppCommands(program2) {
     }
   });
 }
-var APP_CHECK_RULES, APP_CHECK_CODES, SRC_EXT, SKIP_DIRS, NON_SERVICE_DIRS, RE_HTML, RE_OIDC, RE_COOKIE, RE_LOGGER, RE_EXPOSURE, RE_POINTER, RE_METADATA, RE_IAC_GRANT, RE_POINTER_OVERRIDE, RE_PASSWORD, RE_ALLOWLIST, RE_USERS_TABLE, RE_SURFACE_NEW, RE_APIDOCS_NEW, RE_IDENTITY_NEW, RE_IDENTITY_BINDING, DEFAULT_PARTNER_DOCS_ROLES, DOCS_SITE_FIELDS, DOCS_SITE_RETIRED_FIELDS, RE_PROPERTY;
+var APP_CHECK_RULES, APP_CHECK_CODES, SRC_EXT, SKIP_DIRS, NON_SERVICE_DIRS, RE_HTML, RE_OIDC, RE_COOKIE, RE_LOGGER, RE_EXPOSURE, RE_POINTER, RE_METADATA, RE_IAC_GRANT, RE_POINTER_OVERRIDE, RE_PASSWORD, RE_ALLOWLIST, RE_USERS_TABLE, RE_SURFACE_NEW, RE_APIDOCS_NEW, RE_IDENTITY_NEW, RE_EVENTS_NEW, EVENTS_PROJECT_ROLES, RE_IDENTITY_BINDING, DEFAULT_PARTNER_DOCS_ROLES, DOCS_SITE_FIELDS, DOCS_SITE_RETIRED_FIELDS, RE_PROPERTY;
 var init_app_check = __esm({
   "libs/mesh-cli/src/commands/app-check.ts"() {
     "use strict";
@@ -12242,6 +12282,13 @@ var init_app_check = __esm({
         remediation: `declare every audience role on the ZitadelAppIdentity (roles: ["docs"]) so the Hub can grant it from the app's Access tab \u2014 the audience is published on the surface's registry entry as the reader set for the Hub to admit by, and a role nobody can be granted admits nobody`,
         scope: "app"
       },
+      EVENTS_ROLES_UNDECLARED: {
+        gate: "H",
+        title: "Events roles grantable from the Hub",
+        severity: "block",
+        remediation: "spread mesh.apps.EVENTS_PROJECT_ROLES into the ZitadelAppIdentity's roles (roles: [...schemaDef.coarseRoles, ...mesh.apps.EVENTS_PROJECT_ROLES]) so events:subscriber and events:admin are project roles the Hub's Access tab can grant \u2014 the primitive cannot add them, because the identity builds its roles before the events service exists and a role added afterwards is absent from the coarseRoles the Hub reads",
+        scope: "app"
+      },
       DOCS_VENDOR_AUDIENCE_PARTNER: {
         gate: "H",
         title: "Vendor reference never partner-readable",
@@ -12273,7 +12320,7 @@ var init_app_check = __esm({
     RE_OIDC = /openid-client|code_verifier|authorization_code|buildAuthorizeUrl|end_session/;
     RE_COOKIE = /setCookie\(|hono\/cookie|Set-Cookie/;
     RE_LOGGER = /from ["'](pino|hono\/logger|winston|bunyan)["']|require\(["'](pino|winston|bunyan)["']\)|^[^/*]*\bconsole\.(log|info|warn|error)\(/;
-    RE_EXPOSURE = /ZitadelAppIdentity|createOAuthMiddleware|createAuthorizationMiddleware|zitadelJwtScheme|createAuthzMiddleware|bearerAuth|type: *"oidc"|^\s+auth: *\{|_ROLES *= *\{|coarseRoles|ZITADEL_(AUDIENCE|CLIENT_ID)|OIDC_CLIENT_ID|zitadel\.(ApplicationOidc|ApplicationApi|Project|UserGrant)\(/;
+    RE_EXPOSURE = /ZitadelAppIdentity|createOAuthMiddleware|createAuthorizationMiddleware|zitadelJwtScheme|createAuthzMiddleware|bearerAuth|type: *"oidc"|^\s+auth: *\{|_ROLES *= *\{|coarseRoles|ZITADEL_(AUDIENCE|CLIENT_ID)|OIDC_CLIENT_ID|zitadel\.(ApplicationOidc|ApplicationApi|Project|UserGrant)\(|mesh\.apps\.EventsService\(/;
     RE_POINTER = /AppAuthzPointer/;
     RE_METADATA = /compileOpsHubMetadata|ops-hub-metadata|SpiceDBSchema/;
     RE_IAC_GRANT = /userId: *"[0-9]{6,}"/;
@@ -12284,6 +12331,8 @@ var init_app_check = __esm({
     RE_SURFACE_NEW = /new\s+mesh\.apps\.(ApiSurface|AppApiSurface|VendorApiSurface|Integration)\s*\(/g;
     RE_APIDOCS_NEW = /new\s+mesh\.apps\.ApiDocs\s*\(/g;
     RE_IDENTITY_NEW = /new\s+mesh\.auth\.(ZitadelAppIdentity)\s*\(/g;
+    RE_EVENTS_NEW = /new\s+mesh\.apps\.(EventsService)\s*\(/g;
+    EVENTS_PROJECT_ROLES = ["events:subscriber", "events:admin"];
     RE_IDENTITY_BINDING = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::[^=]+)?=\s*new\s+mesh\.auth\.ZitadelAppIdentity\s*\(/g;
     DEFAULT_PARTNER_DOCS_ROLES = ["docs"];
     DOCS_SITE_FIELDS = ["pages", "playground", "audience", "basePath", "ingress", "auth"];
@@ -13507,7 +13556,13 @@ var init_scaffold_versions = __esm({
     "use strict";
     SCAFFOLD_PACKAGE_LINES = {
       "@mesh-tech/app-kit": "^1.45.0",
-      "@mesh-tech/esm-bundle": "^0.1.1"
+      "@mesh-tech/esm-bundle": "^0.1.1",
+      // The events service versions with the primitive that deploys it, not with
+      // the lockstep group, so it carries its own floor.
+      "@mesh-tech/events-service": "^0.1.0",
+      // Likewise authz: it is not in the `fixed` group in .changeset/config.json,
+      // so the lockstep range resolves to a major line it has never published.
+      "@mesh-tech/authz": "^1.19.0"
     };
     SCAFFOLD_TOOLCHAIN = {
       "@types/node": "^24.2.1",
@@ -13676,6 +13731,10 @@ async function promptForOptions(options) {
     primitives.push("service");
     logInfo("Added 'service' \u2014 bucket requires an API service for S3 helpers.");
   }
+  if (primitives.includes("events") && !primitives.includes("service")) {
+    primitives.push("service");
+    logInfo("Added 'service' \u2014 the events publisher lives in the api/ directory.");
+  }
   return { tenant, name, primitives };
 }
 function copyTemplate(srcDir, destDir, context) {
@@ -13787,6 +13846,13 @@ function generateComposableApp(appDir, context) {
     }
     copyTemplate(bucketDir, appDir, context);
   }
+  if (context.events) {
+    const eventsDir = path27.join(fragmentsDir, "events");
+    if (!fs25.existsSync(eventsDir)) {
+      throw new Error(`Fragment directory not found: ${eventsDir}`);
+    }
+    copyTemplate(eventsDir, appDir, context);
+  }
   const agentsDir = path27.join(fragmentsDir, "agents");
   if (fs25.existsSync(agentsDir)) {
     copyTemplate(agentsDir, appDir, context);
@@ -13853,6 +13919,10 @@ function registerCreateAppCommand(program2) {
       primitives.push("service");
       logInfo("Added 'service' \u2014 bucket requires an API service for S3 helpers.");
     }
+    if (primitives.includes("events") && !primitives.includes("service")) {
+      primitives.push("service");
+      logInfo("Added 'service' \u2014 the events publisher lives in the api/ directory.");
+    }
     await runComposable(tenant, name, primitives, options.test);
   });
 }
@@ -13961,6 +14031,8 @@ async function runComposable(tenant, name, primitives, test) {
   const repoRoot2 = resolveTargetRoot(process.cwd());
   const mesh = workspaceDeps ? { range: "", resolved: true } : resolvePublishedRange("@mesh-tech/app-kit", repoRoot2);
   const esmBundle = workspaceDeps ? { range: "", resolved: true } : resolvePublishedRange("@mesh-tech/esm-bundle", repoRoot2);
+  const eventsService = workspaceDeps || !primitives.includes("events") ? { range: "", resolved: true } : resolvePublishedRange("@mesh-tech/events-service", repoRoot2);
+  const authz = workspaceDeps || !primitives.includes("events") ? { range: "", resolved: true } : resolvePublishedRange("@mesh-tech/authz", repoRoot2);
   if (!workspaceDeps) {
     logInfo(
       mesh.resolved ? `@mesh-tech/* pinned to ${mesh.range} (current published line)` : `Registry lookup unavailable \u2014 pinning @mesh-tech/* to ${mesh.range}; run \`pnpm up @mesh-tech/*\` once you have registry auth`
@@ -13973,10 +14045,13 @@ async function runComposable(tenant, name, primitives, test) {
     database: primitives.includes("database"),
     temporal: primitives.includes("temporal"),
     bucket: primitives.includes("bucket"),
+    events: primitives.includes("events"),
     region,
     workspaceDeps,
     meshRange: mesh.range,
     esmBundleRange: esmBundle.range,
+    eventsServiceRange: eventsService.range,
+    authzRange: authz.range,
     typesNodeRange: SCAFFOLD_TOOLCHAIN["@types/node"],
     tsxRange: SCAFFOLD_TOOLCHAIN.tsx,
     typescriptRange: SCAFFOLD_TOOLCHAIN.typescript,
@@ -14091,7 +14166,8 @@ var init_create_app = __esm({
       service: "HTTP Service (API with Hono)",
       database: "Database (PostgreSQL via Prisma)",
       temporal: "Temporal (workflow orchestration)",
-      bucket: "S3 Bucket (file storage)"
+      bucket: "S3 Bucket (file storage)",
+      events: "Events and webhooks (publish, subscriptions, signed delivery)"
     };
     HUB_ACCOUNTS = {
       mesh: "159923586610"
@@ -16931,6 +17007,31 @@ import * as net12 from "node:net";
 import * as os9 from "node:os";
 import * as path36 from "node:path";
 import chalk3 from "chalk";
+function hubSessionName(apiPort) {
+  return `${HUB_SESSION_PREFIX}-${apiPort}`;
+}
+function isHubSession(name) {
+  return HUB_SESSION_RE.test(name);
+}
+function listHubSessions() {
+  try {
+    return execFileSync24("tmux", ["list-sessions", "-F", "#{session_name}"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).split("\n").map((line) => line.trim()).filter(isHubSession);
+  } catch {
+    return [];
+  }
+}
+function killTargets(live, named) {
+  return named ? live.filter((name) => name === named) : live;
+}
+function killInstructions(targets) {
+  return targets.map((name) => {
+    const port = name.slice(HUB_SESSION_PREFIX.length + 1);
+    return port ? `  ${name}: mesh hub dev --kill --api-port ${port}` : `  ${name}: tmux kill-session -t ${name}`;
+  });
+}
 function devSessionsDir() {
   return path36.join(os9.tmpdir(), "mesh-dev-sessions");
 }
@@ -17158,8 +17259,8 @@ function isPortListening2(port) {
     socket.once("error", () => done(false));
   });
 }
-function hubEnvDir() {
-  return path36.join(os9.tmpdir(), "mesh-dev-sessions", HUB_SESSION);
+function hubEnvDir(sessionName) {
+  return path36.join(os9.tmpdir(), "mesh-dev-sessions", sessionName);
 }
 function parsePort(raw, fallback, source) {
   if (raw === void 0) return fallback;
@@ -17181,17 +17282,28 @@ function redactEnv(env) {
 }
 async function hubDevAction(opts) {
   if (opts.kill) {
-    if (tmuxSessionExists(HUB_SESSION)) {
-      execFileSync24("tmux", ["kill-session", "-t", HUB_SESSION], { stdio: "ignore" });
-      fs29.rmSync(hubEnvDir(), { recursive: true, force: true });
-      logSuccess(`Killed Hub session '${HUB_SESSION}'.`);
-    } else {
-      logInfo(`No '${HUB_SESSION}' tmux session running.`);
+    const namedPort = opts.apiPort || process.env.MESH_HUB_DEV_API_PORT;
+    const named = namedPort ? hubSessionName(parsePort(namedPort, DEFAULT_HUB_API_PORT, opts.apiPort ? "--api-port" : "MESH_HUB_DEV_API_PORT")) : null;
+    const targets = killTargets(listHubSessions(), named);
+    if (targets.length === 0) {
+      logInfo(named ? `No '${named}' tmux session running.` : "No `mesh hub dev` session running.");
+      return;
     }
+    if (targets.length > 1) {
+      throw new MeshCliError(
+        `${targets.length} Hub sessions are running \u2014 name the one to stop.
+${killInstructions(targets).join("\n")}`,
+        { remediation: { command: "mesh hub dev --kill --api-port <port>   # the API port that Hub was started on" } }
+      );
+    }
+    const target = targets[0];
+    execFileSync24("tmux", ["kill-session", "-t", target], { stdio: "ignore" });
+    fs29.rmSync(hubEnvDir(target), { recursive: true, force: true });
+    logSuccess(`Killed Hub session '${target}'.`);
     return;
   }
   const uiPort = opts.port ? parsePort(opts.port, DEFAULT_HUB_UI_PORT, "--port") : parsePort(process.env.MESH_HUB_DEV_PORT, DEFAULT_HUB_UI_PORT, "MESH_HUB_DEV_PORT");
-  const apiPort = parsePort(opts.apiPort, DEFAULT_HUB_API_PORT, "--api-port");
+  const apiPort = opts.apiPort ? parsePort(opts.apiPort, DEFAULT_HUB_API_PORT, "--api-port") : parsePort(process.env.MESH_HUB_DEV_API_PORT, DEFAULT_HUB_API_PORT, "MESH_HUB_DEV_API_PORT");
   const platformDir = resolvePlatformDir(opts.platformDir, process.cwd());
   const cwdAppRoot = findAppRoot(process.cwd());
   const session = pickDevSession(listDevSessions(), { session: opts.session, cwdAppRoot });
@@ -17218,9 +17330,10 @@ async function hubDevAction(opts) {
     for (const [k, v] of Object.entries(redactEnv(assembled.uiEnv))) console.log(`  ${k}=${v}`);
     return;
   }
-  if (tmuxSessionExists(HUB_SESSION)) {
-    throw new MeshCliError(`A '${HUB_SESSION}' tmux session is already running.`, {
-      remediation: { command: "mesh hub dev --kill   # then re-run mesh hub dev" }
+  const hubSession = hubSessionName(apiPort);
+  if (tmuxSessionExists(hubSession)) {
+    throw new MeshCliError(`A '${hubSession}' tmux session is already running.`, {
+      remediation: { command: `mesh hub dev --kill --api-port ${apiPort}   # then re-run` }
     });
   }
   for (const [label, port, flag] of [
@@ -17245,20 +17358,20 @@ async function hubDevAction(opts) {
   for (const warning of assembled.warnings) logWarn(warning);
   const apiDir = path36.join(platformDir, "apps", "hub", "api");
   const uiDir = path36.join(platformDir, "apps", "hub", "ui");
-  execFileSync24("tmux", ["new-session", "-d", "-s", HUB_SESSION, "-n", "api", "-c", apiDir]);
+  execFileSync24("tmux", ["new-session", "-d", "-s", hubSession, "-n", "api", "-c", apiDir]);
   if (!assembled.apiEnv.DEV_USER_TOKEN_URL && assembled.apiEnv.DEV_USER_ID_TOKEN) {
     const platform = session.state.devOutput.platform;
     const credContext = `mesh.${platform.env}`;
     const tokenPort = await findFreePort4();
     const tokenUrl = `http://127.0.0.1:${tokenPort}`;
-    execFileSync24("tmux", ["new-window", "-t", HUB_SESSION, "-n", "token-server", "-c", platformDir]);
-    execFileSync24("tmux", ["set-option", "-t", `${HUB_SESSION}:token-server`, "remain-on-exit", "on"], {
+    execFileSync24("tmux", ["new-window", "-t", hubSession, "-n", "token-server", "-c", platformDir]);
+    execFileSync24("tmux", ["set-option", "-t", `${hubSession}:token-server`, "remain-on-exit", "on"], {
       stdio: "ignore"
     });
     execFileSync24("tmux", [
       "send-keys",
       "-t",
-      `${HUB_SESSION}:token-server`,
+      `${hubSession}:token-server`,
       `npx mesh dev __token-server ${tokenPort} ${credContext}`,
       "Enter"
     ]);
@@ -17270,15 +17383,15 @@ async function hubDevAction(opts) {
     logSuccess(`Dev-user token-server: ${tokenUrl} (context ${credContext})`);
   }
   const launch = (window, dir, env, cmd, createWindow) => {
-    const envFile = path36.join(hubEnvDir(), `${window}.env.sh`);
+    const envFile = path36.join(hubEnvDir(hubSession), `${window}.env.sh`);
     writeEnvFile(envFile, env);
     if (createWindow) {
-      execFileSync24("tmux", ["new-window", "-t", HUB_SESSION, "-n", window, "-c", dir]);
+      execFileSync24("tmux", ["new-window", "-t", hubSession, "-n", window, "-c", dir]);
     }
-    execFileSync24("tmux", ["set-option", "-t", `${HUB_SESSION}:${window}`, "remain-on-exit", "on"], {
+    execFileSync24("tmux", ["set-option", "-t", `${hubSession}:${window}`, "remain-on-exit", "on"], {
       stdio: "ignore"
     });
-    execFileSync24("tmux", ["send-keys", "-t", `${HUB_SESSION}:${window}`, buildLaunchCommand(envFile, dir, cmd), "Enter"]);
+    execFileSync24("tmux", ["send-keys", "-t", `${hubSession}:${window}`, buildLaunchCommand(envFile, dir, cmd), "Enter"]);
   };
   launch("api", apiDir, assembled.apiEnv, "pnpm dev", false);
   launch("ui", uiDir, assembled.uiEnv, `pnpm dev --port ${uiPort} --strictPort`, true);
@@ -17288,15 +17401,15 @@ async function hubDevAction(opts) {
   if (!apiUp || !uiUp) {
     throw new MeshCliError(
       `Hub ${apiUp ? "UI" : "API"} did not start listening (api :${apiPort}, ui :${uiPort}).`,
-      { remediation: { command: `tmux attach -t ${HUB_SESSION}   # inspect the ${apiUp ? "ui" : "api"} window` } }
+      { remediation: { command: `tmux attach -t ${hubSession}   # inspect the ${apiUp ? "ui" : "api"} window` } }
     );
   }
   console.log("");
   logSuccess(`Mesh Hub (dev-local scope ${assembled.scope.scopeTenants.join(",")} @ ${assembled.scope.scopeEnv})`);
   console.log(`  ${chalk3.bold.cyan(`http://localhost:${uiPort}`)}  (also reachable on your tailnet)`);
   console.log(`  api  http://localhost:${apiPort}`);
-  console.log(`  logs tmux attach -t ${HUB_SESSION}`);
-  console.log(`  stop mesh hub dev --kill`);
+  console.log(`  logs tmux attach -t ${hubSession}`);
+  console.log(`  stop mesh hub dev --kill --api-port ${apiPort}`);
 }
 function registerHubCommands(program2) {
   const hub = program2.command("hub").description("Local Hub over dev-local stacks");
@@ -17305,9 +17418,15 @@ function registerHubCommands(program2) {
   ).option("--session <name>", "dev session to observe (default: auto-detect from cwd)").option("--tenants <list>", "comma-separated HUB_SCOPE_TENANTS override (default: the session's tenant)").option(
     "--audience <who>",
     "who the Hub renders for: `operator` (platform staff \u2014 the default here) or `tenant` (a client's operators). Anything else reads as `tenant`"
-  ).option("--port <port>", `Hub UI host port (default: $MESH_HUB_DEV_PORT or ${DEFAULT_HUB_UI_PORT})`).option("--api-port <port>", `Hub API port (default: ${DEFAULT_HUB_API_PORT})`).option("--platform-dir <dir>", "mesh-platform checkout to run the Hub from (default: $MESH_PLATFORM_DIR or walk up from cwd)").option("--print-env", "print the assembled env (secrets redacted) and exit without launching").option("--kill", "tear down the running Hub session").action(hubDevAction);
-}
-var HUB_SESSION, DEFAULT_HUB_UI_PORT, DEFAULT_HUB_API_PORT, FORWARD_PREFIXES, localPlatformEnv2, SENSITIVE_RE;
+  ).option("--port <port>", `Hub UI host port (default: $MESH_HUB_DEV_PORT or ${DEFAULT_HUB_UI_PORT})`).option(
+    "--api-port <port>",
+    `Hub API port, and the key its tmux session is named after \u2014 several Hubs coexist on different ones (default: $MESH_HUB_DEV_API_PORT or ${DEFAULT_HUB_API_PORT})`
+  ).option("--platform-dir <dir>", "mesh-platform checkout to run the Hub from (default: $MESH_PLATFORM_DIR or walk up from cwd)").option("--print-env", "print the assembled env (secrets redacted) and exit without launching").option(
+    "--kill",
+    "tear down a running Hub session; with several up, name it with --api-port (or $MESH_HUB_DEV_API_PORT)"
+  ).action(hubDevAction);
+}
+var HUB_SESSION_PREFIX, HUB_SESSION_RE, DEFAULT_HUB_UI_PORT, DEFAULT_HUB_API_PORT, FORWARD_PREFIXES, localPlatformEnv2, SENSITIVE_RE;
 var init_hub = __esm({
   "libs/mesh-cli/src/commands/hub/index.ts"() {
     "use strict";
@@ -17317,7 +17436,8 @@ var init_hub = __esm({
     init_stack();
     init_log();
     init_pulumi();
-    HUB_SESSION = "mesh-hub-dev";
+    HUB_SESSION_PREFIX = "mesh-hub-dev";
+    HUB_SESSION_RE = new RegExp(`^${HUB_SESSION_PREFIX}(-\\d+)?$`);
     DEFAULT_HUB_UI_PORT = Number(DEFAULT_HUB_PORT);
     DEFAULT_HUB_API_PORT = 3002;
     FORWARD_PREFIXES = ["AWS_", "DEV_USER_"];