@mesh-tech/mesh-cli 0.31.0 → 0.32.0

package/dist/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "68b5be22a",
-  "builtAt": "2026-09-21T18:16:49.857Z"
+  "commit": "0ba7b694d",
+  "builtAt": "2026-09-22T18:04:19.382Z"
 }

package/dist/src/commands/hub/index.d.ts

@@ -1,6 +1,11 @@
 import { Command } from "commander";
 import { type SessionState } from "../dev.js";
-export declare const HUB_SESSION = "mesh-hub-dev";
+export declare const HUB_SESSION_PREFIX = "mesh-hub-dev";
+export declare function hubSessionName(apiPort: number): string;
+export declare function isHubSession(name: string): boolean;
+export declare function listHubSessions(): string[];
+export declare function killTargets(live: string[], named: string | null): string[];
+export declare function killInstructions(targets: string[]): string[];
 export declare const DEFAULT_HUB_UI_PORT: number;
 export declare const DEFAULT_HUB_API_PORT = 3002;
 export interface DiscoveredSession {

package/dist/src/commands/hub/index.js

@@ -10,7 +10,37 @@ import { MeshCliError } from "../../utils/errors.js";
 import { DEFAULT_HUB_PORT } from "../local/stack.js";
 import { logInfo, logSuccess, logWarn } from "../../utils/log.js";
 import { findAppRoot } from "../../utils/pulumi.js";
-export const HUB_SESSION = "mesh-hub-dev";
+export const HUB_SESSION_PREFIX = "mesh-hub-dev";
+export function hubSessionName(apiPort) {
+    return `${HUB_SESSION_PREFIX}-${apiPort}`;
+}
+const HUB_SESSION_RE = new RegExp(`^${HUB_SESSION_PREFIX}(-\\d+)?$`);
+export function isHubSession(name) {
+    return HUB_SESSION_RE.test(name);
+}
+export function listHubSessions() {
+    try {
+        return execFileSync("tmux", ["list-sessions", "-F", "#{session_name}"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        })
+            .split("\n")
+            .map((line) => line.trim())
+            .filter(isHubSession);
+    }
+    catch {
+        return [];
+    }
+}
+export function killTargets(live, named) {
+    return named ? live.filter((name) => name === named) : live;
+}
+export 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}`;
+    });
+}
 export const DEFAULT_HUB_UI_PORT = Number(DEFAULT_HUB_PORT);
 export const DEFAULT_HUB_API_PORT = 3002;
 export function devSessionsDir() {
@@ -162,8 +192,12 @@ export function assembleHubEnv(session, sessionEnv, opts) {
         PORT: String(opts.uiPort),
         API_URL: `http://localhost:${opts.apiPort}`,
         HUB_TENANT: hubTenant,
+        HUB_SCOPE_ENV: scopeEnv,
         DEFAULT_ORG: scopeTenants[0],
         DEFAULT_ENV: scopeEnv,
+        ...(process.env.HUB_PEER_ENVIRONMENTS
+            ? { HUB_PEER_ENVIRONMENTS: process.env.HUB_PEER_ENVIRONMENTS }
+            : {}),
         ...audienceEnv,
     };
     return { apiEnv, uiEnv, scope: { hubTenant, scopeEnv, scopeTenants }, temporalAddress, warnings, notes };
@@ -244,8 +278,8 @@ function isPortListening(port) {
         socket.once("error", () => done(false));
     });
 }
-function hubEnvDir() {
-    return path.join(os.tmpdir(), "mesh-dev-sessions", HUB_SESSION);
+function hubEnvDir(sessionName) {
+    return path.join(os.tmpdir(), "mesh-dev-sessions", sessionName);
 }
 export function parsePort(raw, fallback, source) {
     if (raw === undefined)
@@ -269,20 +303,30 @@ export function redactEnv(env) {
 }
 async function hubDevAction(opts) {
     if (opts.kill) {
-        if (tmuxSessionExists(HUB_SESSION)) {
-            execFileSync("tmux", ["kill-session", "-t", HUB_SESSION], { stdio: "ignore" });
-            fs.rmSync(hubEnvDir(), { recursive: true, force: true });
-            logSuccess(`Killed Hub session '${HUB_SESSION}'.`);
+        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;
         }
-        else {
-            logInfo(`No '${HUB_SESSION}' tmux session running.`);
+        if (targets.length > 1) {
+            throw new MeshCliError(`${targets.length} Hub sessions are running — name the one to stop.\n${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];
+        execFileSync("tmux", ["kill-session", "-t", target], { stdio: "ignore" });
+        fs.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 });
@@ -305,9 +349,10 @@ async function hubDevAction(opts) {
             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 [
@@ -329,20 +374,20 @@ async function hubDevAction(opts) {
         logWarn(warning);
     const apiDir = path.join(platformDir, "apps", "hub", "api");
     const uiDir = path.join(platformDir, "apps", "hub", "ui");
-    execFileSync("tmux", ["new-session", "-d", "-s", HUB_SESSION, "-n", "api", "-c", apiDir]);
+    execFileSync("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 findFreePort();
         const tokenUrl = `http://127.0.0.1:${tokenPort}`;
-        execFileSync("tmux", ["new-window", "-t", HUB_SESSION, "-n", "token-server", "-c", platformDir]);
-        execFileSync("tmux", ["set-option", "-t", `${HUB_SESSION}:token-server`, "remain-on-exit", "on"], {
+        execFileSync("tmux", ["new-window", "-t", hubSession, "-n", "token-server", "-c", platformDir]);
+        execFileSync("tmux", ["set-option", "-t", `${hubSession}:token-server`, "remain-on-exit", "on"], {
             stdio: "ignore",
         });
         execFileSync("tmux", [
             "send-keys",
             "-t",
-            `${HUB_SESSION}:token-server`,
+            `${hubSession}:token-server`,
             `npx mesh dev __token-server ${tokenPort} ${credContext}`,
             "Enter",
         ]);
@@ -354,15 +399,15 @@ async function hubDevAction(opts) {
         logSuccess(`Dev-user token-server: ${tokenUrl} (context ${credContext})`);
     }
     const launch = (window, dir, env, cmd, createWindow) => {
-        const envFile = path.join(hubEnvDir(), `${window}.env.sh`);
+        const envFile = path.join(hubEnvDir(hubSession), `${window}.env.sh`);
         writeEnvFile(envFile, env);
         if (createWindow) {
-            execFileSync("tmux", ["new-window", "-t", HUB_SESSION, "-n", window, "-c", dir]);
+            execFileSync("tmux", ["new-window", "-t", hubSession, "-n", window, "-c", dir]);
         }
-        execFileSync("tmux", ["set-option", "-t", `${HUB_SESSION}:${window}`, "remain-on-exit", "on"], {
+        execFileSync("tmux", ["set-option", "-t", `${hubSession}:${window}`, "remain-on-exit", "on"], {
             stdio: "ignore",
         });
-        execFileSync("tmux", ["send-keys", "-t", `${HUB_SESSION}:${window}`, buildLaunchCommand(envFile, dir, cmd), "Enter"]);
+        execFileSync("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);
@@ -370,14 +415,14 @@ async function hubDevAction(opts) {
     const apiUp = await waitForPort("127.0.0.1", apiPort, 90_000);
     const uiUp = apiUp && (await waitForPort("127.0.0.1", uiPort, 90_000));
     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` } });
+        throw new MeshCliError(`Hub ${apiUp ? "UI" : "API"} did not start listening (api :${apiPort}, ui :${uiPort}).`, { 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(`  ${chalk.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}`);
 }
 export function registerHubCommands(program) {
     const hub = program.command("hub").description("Local Hub over dev-local stacks");
@@ -388,9 +433,9 @@ export function registerHubCommands(program) {
         .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 — 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("--api-port <port>", `Hub API port, and the key its tmux session is named after — 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 the running Hub session")
+        .option("--kill", "tear down a running Hub session; with several up, name it with --api-port (or $MESH_HUB_DEV_API_PORT)")
         .action(hubDevAction);
 }

package/fragments/base/README.md.hbs

@@ -7,3 +7,18 @@ locally with `mesh dev`, deploy it with `mesh deploy up`.
 The API's reference site is built by the platform from `api/openapi.json` and
 the guides in `docs/pages/` — this README is its landing page.
 {{/if}}
+
+## The version this app reports
+
+`"version": "0.0.1"` in `package.json` is a STARTING POINT, not the number the
+Hub shows. Every deploy derives the app's version from the conventional commits
+that have landed on this directory since that version was last committed: a
+`fix:` moves the patch, a `feat:` moves the minor, a `feat!:`/`BREAKING CHANGE:`
+moves the major. Redeploying unchanged code stamps the same number, so a
+redeploy is not recorded as a new deploy.
+
+Nothing to run and nothing to remember — the version simply grows with the app,
+and the Hub's Activity tab shows each deploy with the version it shipped. To
+take the number over yourself, commit the version you want into `package.json`
+(the derivation restarts from it) or pass `versioning: "package"` to
+`AppEnvironment`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mesh-tech/mesh-cli",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "CLI for Mesh platform development utilities",
   "type": "module",
   "license": "UNLICENSED",
@@ -42,7 +42,7 @@
   },
   "devDependencies": {
     "@mesh-tech/agent-contracts": "0.2.0",
-    "@mesh-tech/tsconfig": "2.23.0",
+    "@mesh-tech/tsconfig": "2.26.0",
     "@mesh-tech/workflow-viz": "0.3.0",
     "@tanstack/intent": "^0.3.6",
     "@types/node": "^20.0.0",

package/skills/core/SKILL.md

@@ -95,7 +95,7 @@ Top-level commands (each `register*` is wired in `src/program.ts`, which `bin/me
 | `mesh deploy ...` | passthrough | Runs `pulumi` with the stack's `mesh:deployerRole` assumed. Unknown opts/args pass through; defaults to `up` if no subcommand. | `-s/--stack <name>` (stripped before pulumi `up`); everything else → pulumi (`preview`, `up --yes`, `destroy`, `stack output …`) |
 | `mesh dev` | `logs <service>`, `restart <service>`, `list`, `test-user [name]` | Two modes. **Tethered** (deployed stack): reads the Pulumi stack dev output, opens tunnels, injects Secrets Manager secrets; needs VPN/AWS creds. **Local** (`--local`, auto when the app has no `Pulumi.yaml`): synthesizes services from the app layout (subdirs with a `dev` script, plus a synthesized `dg dev` webserver when the app root is a Dagster workspace — `dg.toml`, or `[tool.dg]` in `pyproject.toml`; such an app runs with zero package.json services — see `docs/guides/local-dagster.md`) and wires them to the `mesh start` platform (Temporal `local-dev`, app DB, Zitadel, ministack via `AWS_ENDPOINT_URL`) — zero AWS/VPN/Pulumi. `--externals` (local mode; `--mock` is an alias) also realizes the app's declared external services (package.json → `mesh.externals`; legacy `mesh.mocks` still read). Each declaration runs in one of three MODES — `mock` (the service is emulated: `openapi` → a Prism mock server from a spec, or `src` → a mock process), `local` (a local version of the real service: a `compose` file + published `port`, e.g. a vendor-shaped DB — up `--wait` before the app's services; a realization another checkout already started is **adopted** instead of failing — declared port already served **by a container this compose file defines** → adopt as-is (a publisher the file doesn't define — a native install or unrelated container — is a hard **conflict**, never adopted, since credentials would seed against the wrong service); a stopped foreign container holding the compose `container_name` → `docker start` + adopt — so startup order across checkouts doesn't matter; adopted externals stay out of session state and `--kill` tears down only externals this session created, volumes kept), `remote` (connect to the ACTUAL service: inline vendor `credentials`, or the credentials the app's tenant environment is configured with via `remote.env`). A declaration may carry SEVERAL realizations; `mode` picks the default and `--externals name=mode` overrides it per run (`--externals plaid-db=remote,plaid`). Remote externals get a blackbox uptime probe against their real endpoint. Failing to realize a remote external is fatal only when you named it; a bare `--externals` warns and keeps going, so the local loop still works with no AWS identity. Every realization seeds its ExternalService credential secret (`{{url}}`/`{{host}}`/`{{port}}` from the stand-in's endpoint, `{{env:VAR}}` from the shell) so `resolveCredentials()` runs the deployed code path against the stand-in. Runners: tmux (default) or `--runner docker` (CI/headless — services run as a docker compose project with host networking; parity `--status`/`--kill`/`logs`/`restart`). | root: `--local`, `--externals [name[=mode],…]` (alias `--mock`), `--runner <tmux\|docker>`, `--app <path>`, `--stage`, `--headless`, `--kill`, `--status`, `--json`, `--session <name>`, `--profile <sso>`; `logs`: `--tail <n>`; `test-user`: `--tenant/--env/--region` |
 | `mesh start` / `mesh stop` / `mesh status` | — | Full-local Mesh platform via docker compose (project `mesh-local`, assets ship in the CLI package): Postgres, Temporal (+UI), Zitadel, SpiceDB, ministack (local AWS fabric: SSM/Secrets/S3 registry; also seeds a general-purpose `mesh-local-data` bucket with sample data — see `docs/guides/local-dagster.md`), memcached, OpenSearch, a **local mailbox** (Mailpit — SMTP :1025 wired into Zitadel, inbox at http://localhost:8025, so user-activation and password-reset mail is testable locally instead of vanishing), **and the hosted observability backends** (OTel collector + Loki + Tempo + Prometheus — the Hub's logs/traces/metrics views run unchanged). Seeds tenant `local`/env `dev` on first boot and reconciles every Zitadel-provisioned app tenant into the registry. **No AWS creds, VPN, or Pulumi state needed — Docker only.** The **Hub is included by default** — three overlay services, `hub-api` + `hub-ui` + `hub-auth` (an oauth2-proxy; it is what binds the front-door port and proxies to `hub-ui`, so front-door 401s/redirect loops are in ITS logs, not `hub-api`'s) — the front door at http://localhost:9000 — `MESH_HUB_PORT=<port>` publishes it elsewhere when 9000 is taken; export it for `mesh status` too (images build once from the published @mesh-tech/hub tarball; needs `mesh registry login` the first time; `--no-hub` opts out). Auth contract: `--with-hub` refreshes to the latest published hub after preflighting the CodeArtifact token — with an expired/missing token it falls back to the already-built local images (warn + fixing command), or fails fast naming `mesh registry login --profile mesh-dev` when none exist; the default (no-flag) path with an expired/missing token starts hub-less and names the same fix. `--hub-from-source` sidesteps the registry entirely — it builds the Hub images from THIS checkout's `apps/hub`, which is the only way to run an unpublished Hub change in the containerized stack. `--with-idps` adds two mock identity providers (SAML + OIDC) and federates the local Zitadel with BOTH, which is how enterprise SSO gets exercised without a cloud tenant — the two-provider shape is deliberate, since the instance login policy carries a LIST of IdPs and the failure worth catching is a second federation evicting the first (`docs/guides/local-federation.md`). Its two host ports (4569 SAML, 5556 OIDC — 5556 is Dex's own default) join the start-up port preflight only when the flag is passed, and `mesh status` lists both mocks once they are running. Non-TTY runs (CI, agents, piped output) get an `[HH:MM:SS]` prefix on every step line plus a heartbeat during long fetches/builds — `MESH_LOG_TIMESTAMPS=1/0` forces the prefix on/off (default: on when stderr is not a TTY). | `start`: `--no-seed`, `--no-hub`, `--with-hub`, `--hub-from-source`, `--with-idps`, `--takeover`, `--skip-port-check`; `stop`: `--destroy` (drops volumes/seeds), `--force`; `status`: `--json` |
-| `mesh hub` | `dev` | One-command local Hub over a running dev-local stack. Launches the CURRENT-CODE Hub (apps/hub api+ui from a mesh-platform checkout) pointed at an existing `mesh dev` session — auto-assembles `HUB_TENANT`/`HUB_SCOPE_ENV`/`HUB_SCOPE_TENANTS` (session platform context), `TEMPORAL_ADDRESS` (session tunnel), `AWS_*` (session scratch profile), `DEV_USER_*`+`DEV_USER_TOKEN_URL` (session dev identity; starts its own token-server if the session predates it, so tokens stay fresh past ~1h). Refuses to launch with an empty tenant scope (which the Hub renders as silently blank). Runs in tmux session `mesh-hub-dev`. | `dev`: `--session <name>`, `--tenants <csv>`, `--port` (or `MESH_HUB_DEV_PORT`, default 9000; the containerized `mesh start` Hub uses the separate `MESH_HUB_PORT`), `--api-port <3002>`, `--platform-dir <dir>` (or `MESH_PLATFORM_DIR`), `--print-env`, `--kill` |
+| `mesh hub` | `dev` | One-command local Hub over a running dev-local stack. Launches the CURRENT-CODE Hub (apps/hub api+ui from a mesh-platform checkout) pointed at an existing `mesh dev` session — auto-assembles `HUB_TENANT`/`HUB_SCOPE_ENV`/`HUB_SCOPE_TENANTS` (session platform context), `TEMPORAL_ADDRESS` (session tunnel), `AWS_*` (session scratch profile), `DEV_USER_*`+`DEV_USER_TOKEN_URL` (session dev identity; starts its own token-server if the session predates it, so tokens stay fresh past ~1h). Refuses to launch with an empty tenant scope (which the Hub renders as silently blank). Runs in tmux session `mesh-hub-dev-<api-port>`, so several local Hubs coexist once each is given an API port of its own (both ports default the same in every worktree). | `dev`: `--session <name>`, `--tenants <csv>`, `--port` (or `MESH_HUB_DEV_PORT`, default 9000; the containerized `mesh start` Hub uses the separate `MESH_HUB_PORT`), `--api-port` (or `MESH_HUB_DEV_API_PORT`, default 3002; also names the tmux session), `--platform-dir <dir>` (or `MESH_PLATFORM_DIR`), `--print-env`, `--kill` |
 | `mesh create-app` | — | Scaffold a tenant app. Composable mode (primitives) or legacy template mode. Interactive when TTY + missing flags. Run at the root of an **empty** `{tenant}-mesh-apps` git clone (a `.git` with no `package.json`/`apps/`/`tenants/` and no enclosing pnpm workspace), it first generates the repo-level shape — `pnpm-workspace.yaml` over `apps/*`, private root `package.json`, scoped-registry `.npmrc`, base `tsconfig.json`, `.gitignore`, `README.md`, `apps/` — then scaffolds the app. Never overwrites an existing file. | `--tenant`, `--name`, `--primitives <csv>` (`service,database,temporal,bucket`), `--template <workflow\|api-auth\|api-role-gating\|external-service>`, `--test` (writes to `tests/tenants/`) |
 | `mesh app` | `check [apps...]` | Checks tenant apps against the **Mesh app contract** (`@mesh-tech/app-kit#apps` → `references/app-contract.md`): a UI is its own Service (`UI_IN_API`, `NO_UI_SERVICE`), the app registers with the Hub (`NO_REGISTER`), sign-in goes through the platform proxy (`CUSTOM_SESSION_AUTH`), logs go through `@mesh-tech/logger` (`NON_PLATFORM_LOGGER`), and people/roles/keys are surfaced through the Hub (`NO_AUTHZ_POINTER`, `METADATA_UNPUBLISHED`, `IAC_GRANTS`, `PASSWORD_STORE`, `EMAIL_ALLOWLIST`, `USERS_TABLE`), and a docs site is published through the Hub docs door rather than on a hostname of its own, with its readers stated and grantable (`DOCS_SITE_PUBLIC` — advisory: the public hostname is the deprecated compatibility path and keeps deploying, so the finding names the door instead — `DOCS_AUDIENCE_IMPLICIT`, `DOCS_AUDIENCE_UNGRANTABLE`, `DOCS_VENDOR_AUDIENCE_PARTNER` — a vendor surface's reference is never partner-readable); a tenant-local auth lib is advisory (`LOCAL_AUTH_LIB`), as is a pointer that names its own Zitadel project instead of binding the env with `zitadelAppProjectId` (`POINTER_PROJECT_OVERRIDE`). Gate 0.6 additionally resolves the Pulumi program's imports against the installed tree (`UNRESOLVABLE_IMPORT`) — an optional peer nothing declares installs silently and `skipLibCheck` hides it, so the break otherwise waits for `mesh deploy`; with no `node_modules` the gate reports itself not checked rather than met. One check per code on the `mesh dev doctor` engine; exit 1 on any BLOCK. The SAME gate `mesh create-app` runs after scaffolding, tenant CI runs beside `mesh skills sync --check`, and the platform reviewer runs on a PR. Default: every `apps/*` with a Pulumi program. | `[apps...]` (repo-relative dirs), `--root <dir>`, `--json`, `--verbose` |
 | `mesh init` | (bare = wizard), `app-tenant`, `platform <tenant>` | **Bare `mesh init` is the guided setup wizard**: tenant (pre-filled from `mesh.json` / Pulumi `mesh:tenant`), **where the tenant runs — local-only, a deployed platform, or NOTHING YET (scaffold one; §1c)**, registry access (in-process `mesh registry login`; a 403 marks the step ✘ and the wizard continues), platform sign-in on the deployed branch only, repo bootstrap (empty clone, or an empty non-git folder the wizard offers to `git init`) or shape check, skills sync; writes `mesh.json` (`{tenant, platform}`) so `create-app` / `mesh dev` default `--tenant`; flags `--tenant --local\|--platform <env>\|--new-platform [env] --device --profile --skip-repo --yes --json`, plus the scaffold's own under `--new-platform` (`--region --domain --state-bucket --create-state-bucket/--no-create-state-bucket --dir`); exit 1 if any step failed, 130 on Ctrl-C. `platform <tenant>` **prompts** on a TTY for env/region/profile/state bucket (defaults on each) and for `--domain`, which has **no** default because a placeholder scaffolds an unvalidatable zone; it offers to create the Pulumi state bucket (versioned) and prints the deploy sequence including the manual NS delegation. `app-tenant` is the repo doctor (A1–A3): read-only check pipeline — CLI auth, registry access, public npm not hijacked, platform reachable (Hub API), app-tenant registration, deployer role, repo shape, agent skills — each failure names the exact `mesh` fix. **Registry access** is a live probe of the CodeArtifact token, not a grep of `~/.npmrc`: an expired token `fail`s (it used to `pass`), an unreachable registry `warn`s (a network fault is not an auth fault). **Public npm not hijacked** fails when `~/.npmrc` carries an unscoped `registry=<codeartifact>` line, which makes CodeArtifact your default registry — one `mesh registry login` fixes both. Exit 0 iff all pass; re-run any time. `--fix` applies developer-scope fixes (registry token, skills sync); operator actions stay remediations — and `--profile <p>` is the SSO profile `--fix` logs into CodeArtifact with, echoed back in the `fix:` command each check prints so the advertised command is the one that runs. | `app-tenant`: `--tenant <name>`, `--context <ctx>` (default `local`), `--hub-url <url>`, `--fix`, `--profile <sso>`, `--json` |
@@ -245,7 +245,8 @@ mesh hub dev                 # → local current-code Hub at http://localhost:90
                              #   scoped to this session's tenant: workflow types with
                              #   live run counts, execution timelines incl. child slices
 mesh hub dev --print-env     # inspect the assembled env without launching
-mesh hub dev --kill          # tear down (tmux session mesh-hub-dev)
+mesh hub dev --api-port 3102 # move the API off 3002 AND name the session (or export MESH_HUB_DEV_API_PORT)
+mesh hub dev --kill          # tear down (tmux session mesh-hub-dev-<api-port>)
 ```
 
 Zero hand-set env vars: the command reads the `mesh dev` session's state file

package/templates/apps-repo/README.md.hbs

@@ -22,3 +22,11 @@ pnpm install
 mesh dev                     # run locally
 mesh deploy up               # deploy via the stack's deployer role
 ```
+
+## App versions
+
+An app's deployed version is derived from its own change set — the conventional
+commits touching `apps/<app>/` since the version in its `package.json` was last
+committed — so it grows on its own and the Hub can show which version each
+deploy shipped. Conventional-commit subjects (`feat:`, `fix:`, `feat!:`) are
+what make the bump meaningful; a subject with no type counts as a patch.