@mesh-tech/mesh-cli 0.20.4 → 0.22.0

package/dist/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "e2a82625e",
-  "builtAt": "2026-09-11T22:29:18.194Z"
+  "commit": "33b979d17",
+  "builtAt": "2026-09-13T19:59:04.523Z"
 }

package/dist/src/commands/app-check.d.ts

@@ -1,6 +1,6 @@
 import { Command } from "commander";
 import { jsonReport, type Check, type CheckResult, type CheckStatus } from "./dev-doctor.js";
-export type AppCheckCode = "UI_IN_API" | "NO_UI_SERVICE" | "NO_REGISTER" | "CUSTOM_SESSION_AUTH" | "NON_PLATFORM_LOGGER" | "LOCAL_AUTH_LIB" | "NO_AUTHZ_POINTER" | "METADATA_UNPUBLISHED" | "IAC_GRANTS" | "POINTER_PROJECT_OVERRIDE" | "PASSWORD_STORE" | "EMAIL_ALLOWLIST" | "USERS_TABLE";
+export type AppCheckCode = "UI_IN_API" | "NO_UI_SERVICE" | "NO_REGISTER" | "CUSTOM_SESSION_AUTH" | "NON_PLATFORM_LOGGER" | "LOCAL_AUTH_LIB" | "NO_AUTHZ_POINTER" | "METADATA_UNPUBLISHED" | "IAC_GRANTS" | "POINTER_PROJECT_OVERRIDE" | "PASSWORD_STORE" | "EMAIL_ALLOWLIST" | "USERS_TABLE" | "DOCS_SITE_UNAUTHED" | "DOCS_AUDIENCE_IMPLICIT";
 export interface AppCheckRule {
     gate: string;
     title: string;
@@ -17,6 +17,21 @@ export interface Finding {
 }
 export declare function srcFiles(dir: string): string[];
 export declare function isUiDir(name: string): boolean;
+export declare function balancedSpan(text: string, open: number): string;
+export declare function splitTopLevel(inner: string): string[];
+export declare function stripTrailingComments(value: string): string;
+export declare function topLevelProperties(objectText: string): Map<string, string>;
+export interface SurfaceDeclaration {
+    ctor: string;
+    body: string;
+    line: number;
+}
+export declare function surfaceDeclarations(text: string, pattern?: RegExp): SurfaceDeclaration[];
+export declare function docsSiteFindings(text: string): Array<{
+    code: AppCheckCode;
+    line: number;
+    why: string;
+}>;
 export declare function listApps(root: string): string[];
 export declare function scanApp(root: string, appRel: string): Finding[];
 export declare function scanRepo(root: string): Finding[];

package/dist/src/commands/app-check.js

@@ -96,6 +96,20 @@ export const APP_CHECK_RULES = {
         remediation: "drop the table; people and roles live in Zitadel and are administered from the Hub",
         scope: "app",
     },
+    DOCS_SITE_UNAUTHED: {
+        gate: "0.3",
+        title: "Docs site behind the platform sign-in",
+        severity: "block",
+        remediation: 'on an API surface: docs: { auth: { clientId, clientSecret } } (or a client on surfaces.http.auth), or opt out with docs: { site: false }; on a mesh.apps.ApiDocs: auth: { provider: "mesh", clientId, clientSecret }, or drop the ingress (an in-cluster site is reachable through mesh dev)',
+        scope: "app",
+    },
+    DOCS_AUDIENCE_IMPLICIT: {
+        gate: "H",
+        title: "Docs audience stated, not derived",
+        severity: "block",
+        remediation: 'declare the surface as mesh.apps.AppApiSurface or VendorApiSurface (or pass kind: "app" | "vendor"), or state docs: { audience: { roles: […] } }',
+        scope: "app",
+    },
 };
 export const APP_CHECK_CODES = Object.keys(APP_CHECK_RULES);
 const SRC_EXT = new Set([".ts", ".tsx", ".js", ".mjs", ".jsx"]);
@@ -227,6 +241,250 @@ const RE_POINTER_OVERRIDE = /\bzitadel: *\{\s*projectId\b/;
 const RE_PASSWORD = /(^|[^a-z])(bcrypt|argon2)|password_hash|passwordHash|hashPassword|temporaryPassword.*(send|mail)|(send|mail).*temporaryPassword/;
 const RE_ALLOWLIST = /ADMIN_EMAILS|ALLOWED_EMAILS|allowedEmails|adminEmails/;
 const RE_USERS_TABLE = /create table (if not exists )?"?(users|roles|user_roles|permissions)"?/i;
+const RE_SURFACE_NEW = /new\s+mesh\.apps\.(ApiSurface|AppApiSurface|VendorApiSurface|Integration)\s*\(/g;
+const RE_APIDOCS_NEW = /new\s+mesh\.apps\.ApiDocs\s*\(/g;
+const DOCS_SITE_FIELDS = ["pages", "playground", "audience", "basePath", "ingress", "auth"];
+const RE_DEV_BYPASS = /^["']dev-bypass["']$/;
+export function balancedSpan(text, open) {
+    const closers = { "(": ")", "{": "}", "[": "]" };
+    const stack = [];
+    let quote;
+    for (let i = open; i < text.length; i++) {
+        const ch = text[i];
+        if (quote) {
+            if (ch === "\\")
+                i++;
+            else if (ch === quote)
+                quote = undefined;
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === "`") {
+            quote = ch;
+            continue;
+        }
+        if (ch === "/" && text[i + 1] === "/") {
+            const eol = text.indexOf("\n", i);
+            if (eol === -1)
+                return "";
+            i = eol;
+            continue;
+        }
+        if (ch === "/" && text[i + 1] === "*") {
+            const end = text.indexOf("*/", i + 2);
+            if (end === -1)
+                return "";
+            i = end + 1;
+            continue;
+        }
+        if (closers[ch])
+            stack.push(closers[ch]);
+        else if (ch === ")" || ch === "}" || ch === "]") {
+            if (stack.pop() !== ch)
+                return "";
+            if (stack.length === 0)
+                return text.slice(open, i + 1);
+        }
+    }
+    return "";
+}
+export function splitTopLevel(inner) {
+    const parts = [];
+    let depth = 0;
+    let quote;
+    let start = 0;
+    for (let i = 0; i < inner.length; i++) {
+        const ch = inner[i];
+        if (quote) {
+            if (ch === "\\")
+                i++;
+            else if (ch === quote)
+                quote = undefined;
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === "`") {
+            quote = ch;
+            continue;
+        }
+        if (ch === "/" && inner[i + 1] === "/") {
+            const eol = inner.indexOf("\n", i);
+            if (eol === -1)
+                break;
+            i = eol;
+            continue;
+        }
+        if (ch === "/" && inner[i + 1] === "*") {
+            const end = inner.indexOf("*/", i + 2);
+            if (end === -1)
+                break;
+            i = end + 1;
+            continue;
+        }
+        if (ch === "(" || ch === "{" || ch === "[")
+            depth++;
+        else if (ch === ")" || ch === "}" || ch === "]")
+            depth--;
+        else if (ch === "," && depth === 0) {
+            parts.push(inner.slice(start, i));
+            start = i + 1;
+        }
+    }
+    const last = inner.slice(start);
+    if (last.trim())
+        parts.push(last);
+    return parts;
+}
+const RE_PROPERTY = /^(?:"([^"]+)"|'([^']+)'|([A-Za-z_$][\w$]*))\s*(?::\s*([\s\S]*))?$/;
+function stripLeadingComments(entry) {
+    let text = entry;
+    for (;;) {
+        const next = text.replace(/^\s*(?:\/\/[^\n]*(?:\n|$)|\/\*[\s\S]*?\*\/)/, "");
+        if (next === text)
+            return text;
+        text = next;
+    }
+}
+export function stripTrailingComments(value) {
+    let out = "";
+    let depth = 0;
+    let quote;
+    for (let i = 0; i < value.length; i++) {
+        const ch = value[i];
+        if (quote) {
+            out += ch;
+            if (ch === "\\") {
+                out += value[i + 1] ?? "";
+                i++;
+            }
+            else if (ch === quote)
+                quote = undefined;
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === "`") {
+            quote = ch;
+            out += ch;
+            continue;
+        }
+        if (depth === 0 && ch === "/" && value[i + 1] === "/") {
+            const eol = value.indexOf("\n", i);
+            if (eol === -1)
+                break;
+            i = eol;
+            out += "\n";
+            continue;
+        }
+        if (depth === 0 && ch === "/" && value[i + 1] === "*") {
+            const end = value.indexOf("*/", i + 2);
+            if (end === -1)
+                break;
+            i = end + 1;
+            continue;
+        }
+        if (ch === "(" || ch === "{" || ch === "[")
+            depth++;
+        else if (ch === ")" || ch === "}" || ch === "]")
+            depth--;
+        out += ch;
+    }
+    return out.trim();
+}
+export function topLevelProperties(objectText) {
+    const props = new Map();
+    if (!objectText.startsWith("{") || !objectText.endsWith("}"))
+        return props;
+    for (const entry of splitTopLevel(objectText.slice(1, -1))) {
+        const text = stripLeadingComments(entry).trim();
+        if (!text || text.startsWith("..."))
+            continue;
+        const m = RE_PROPERTY.exec(text);
+        if (!m)
+            continue;
+        const key = m[1] ?? m[2] ?? m[3];
+        props.set(key, stripTrailingComments(m[4] ?? key));
+    }
+    return props;
+}
+function objectLiteralOf(value, program) {
+    if (!value)
+        return undefined;
+    if (value.startsWith("{"))
+        return balancedSpan(value, 0) || undefined;
+    const id = /^[A-Za-z_$][\w$]*$/.exec(value)?.[0];
+    if (!id)
+        return undefined;
+    const decl = new RegExp(`\\bconst\\s+${id}\\s*(?::[^=]+)?=\\s*\\{`).exec(program);
+    return decl ? balancedSpan(program, decl.index + decl[0].length - 1) || undefined : undefined;
+}
+function optionsObject(body) {
+    for (const arg of splitTopLevel(body.slice(1, -1))) {
+        const trimmed = arg.trim();
+        if (trimmed.startsWith("{"))
+            return balancedSpan(trimmed, 0) || undefined;
+    }
+    return undefined;
+}
+export function surfaceDeclarations(text, pattern = RE_SURFACE_NEW) {
+    const out = [];
+    for (const m of text.matchAll(pattern)) {
+        const body = balancedSpan(text, m.index + m[0].length - 1);
+        if (!body)
+            continue;
+        out.push({ ctor: m[1] ?? "ApiDocs", body, line: text.slice(0, m.index).split("\n").length });
+    }
+    return out;
+}
+function isClientAuth(value) {
+    return value !== undefined && value !== "undefined" && !RE_DEV_BYPASS.test(value);
+}
+export function docsSiteFindings(text) {
+    const findings = [];
+    for (const decl of surfaceDeclarations(text)) {
+        const options = optionsObject(decl.body);
+        if (!options)
+            continue;
+        const args = topLevelProperties(options);
+        const docsText = objectLiteralOf(args.get("docs"), text);
+        if (!docsText)
+            continue;
+        const docs = topLevelProperties(docsText);
+        if (docs.get("site") === "false")
+            continue;
+        if (docs.get("site") !== "true" && !DOCS_SITE_FIELDS.some((f) => docs.has(f)))
+            continue;
+        const httpText = objectLiteralOf(topLevelProperties(objectLiteralOf(args.get("surfaces"), text) ?? "{}").get("http"), text);
+        const hasClient = isClientAuth(docs.get("auth")) || isClientAuth(topLevelProperties(httpText ?? "{}").get("auth"));
+        if (!hasClient) {
+            findings.push({
+                code: "DOCS_SITE_UNAUTHED",
+                line: decl.line,
+                why: `mesh.apps.${decl.ctor} declares a docs site with no OIDC client — the site is served behind the platform sign-in proxy, which needs one (docs.auth, or a client on surfaces.http.auth)`,
+            });
+        }
+        const kindStated = decl.ctor === "AppApiSurface" || decl.ctor === "VendorApiSurface" || args.has("kind");
+        if (!kindStated && !docs.has("audience")) {
+            findings.push({
+                code: "DOCS_AUDIENCE_IMPLICIT",
+                line: decl.line,
+                why: `mesh.apps.${decl.ctor} declares a docs site but neither its kind nor its audience — who may read it would fall out of the name heuristic, and a vendor surface must never default to partner-readable that way`,
+            });
+        }
+    }
+    for (const decl of surfaceDeclarations(text, RE_APIDOCS_NEW)) {
+        const options = optionsObject(decl.body);
+        if (!options)
+            continue;
+        const args = topLevelProperties(options);
+        if (!args.has("ingress") || args.get("ingress") === "undefined")
+            continue;
+        if (isClientAuth(args.get("auth")))
+            continue;
+        findings.push({
+            code: "DOCS_SITE_UNAUTHED",
+            line: decl.line,
+            why: `mesh.apps.ApiDocs is published on an ingress with no auth — the site (reference and playground) is reachable by anyone; put the platform sign-in proxy in front of it, or drop the ingress`,
+        });
+    }
+    return findings;
+}
 export function listApps(root) {
     const apps = [];
     const appsDir = path.join(root, "apps");
@@ -281,6 +539,8 @@ export function scanApp(root, appRel) {
         if (!/env\.register\(|\.annotate\(/.test(readText(index))) {
             hit("NO_REGISTER", indexRel, "never calls env.register({…}) — the Hub cannot list this app");
         }
+        for (const f of docsSiteFindings(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);

package/dist/src/commands/create-app.d.ts

@@ -39,4 +39,5 @@ export declare function generateComposableApp(appDir: string, context: {
 export declare function registerCreateAppCommand(program: Command): void;
 export declare const NO_REGISTRY_ACCESS_MESSAGE: string;
 export declare function ensureRegistryAccess(cwd: string, options: Pick<CreateAppOptions, "skipRegistryCheck">, preflight?: () => Promise<RegistryPreflight>): Promise<void>;
+export declare function composableNextSteps(appDir: string, platform: string | null): string[];
 export {};

package/dist/src/commands/create-app.js

@@ -575,13 +575,28 @@ function printComposableNextSteps(appDir, context) {
         console.log("  api/src/storage.ts  S3 helpers");
     }
     console.log("");
-    console.log("Next steps:");
-    console.log(`  cd ${appDir}`);
-    console.log("  pnpm install");
-    console.log("  mesh skills sync         # re-run once deps are installed: picks up package skills + Intent");
-    console.log("  pnpm install             # again only if skills sync reports it added @tanstack/intent");
-    console.log("  mesh stack init          # personal dev stack (deploy: false)");
-    console.log("  mesh deploy up --yes     # deploy via the stack's deployer role");
-    console.log("  mesh dev                 # run locally");
-    console.log("");
+    for (const line of composableNextSteps(appDir, findMeshJson(process.cwd())?.data.platform ?? null)) {
+        console.log(line);
+    }
+}
+export function composableNextSteps(appDir, platform) {
+    const common = [
+        "Next steps:",
+        `  cd ${appDir}`,
+        "  pnpm install",
+        "  mesh skills sync         # re-run once deps are installed: picks up package skills + Intent",
+        "  pnpm install             # again only if skills sync reports it added @tanstack/intent",
+    ];
+    const local = [
+        "  mesh start               # the local Mesh platform (once; Docker — from anywhere)",
+        "  mesh dev                 # run the app against it",
+    ];
+    const deploy = [
+        "  mesh stack init          # personal dev stack (deploy: false)",
+        "  mesh deploy up --yes     # deploy via the stack's deployer role",
+    ];
+    if (platform === null || platform === "local") {
+        return [...common, ...local, "", "When you deploy to a Mesh platform:", ...deploy];
+    }
+    return [...common, ...deploy, "  mesh dev                 # run locally against the platform"];
 }

package/dist/src/commands/local/helpers.d.ts

@@ -1,3 +1,4 @@
+import type { StackEndpoint } from "./stack.js";
 export interface SecretsSender {
     send(command: unknown): Promise<unknown>;
 }
@@ -6,3 +7,20 @@ export declare function probeTcp(port: number, opts?: {
     host?: string;
     timeoutMs?: number;
 }): Promise<boolean>;
+export declare function hostPortsOf(endpoints: ReadonlyArray<Pick<StackEndpoint, "url" | "probe">>): number[];
+export interface PortHolder {
+    kind: "container" | "process";
+    name: string;
+}
+export interface PortConflict {
+    port: number;
+    holder: PortHolder | null;
+}
+export declare function parseDockerPsPorts(output: string, ignorePrefix: string): Map<number, string>;
+export interface PortConflictIo {
+    dockerPs: () => string;
+    processOn: (port: number) => string | null;
+    listening: (port: number) => Promise<boolean>;
+}
+export declare function findPortConflicts(ports: readonly number[], ignorePrefix: string, io?: PortConflictIo): Promise<PortConflict[]>;
+export declare function describePortConflicts(conflicts: readonly PortConflict[], moveHints?: ReadonlyMap<number, string>): string;

package/dist/src/commands/local/helpers.js

@@ -1,4 +1,5 @@
 import * as net from "net";
+import { execFileSync } from "child_process";
 import { LOCAL_AWS_CONFIG } from "./seed.js";
 export async function upsertLocalSecret(secretId, value, client) {
     const { SecretsManagerClient, CreateSecretCommand, PutSecretValueCommand } = await import("@aws-sdk/client-secrets-manager");
@@ -31,3 +32,98 @@ export function probeTcp(port, opts = {}) {
         });
     });
 }
+export function hostPortsOf(endpoints) {
+    const ports = new Set();
+    const fromUrl = (raw) => {
+        try {
+            const u = new URL(raw.includes("://") ? raw : `tcp://${raw}`);
+            const port = Number(u.port || (u.protocol === "https:" ? 443 : u.protocol === "http:" ? 80 : NaN));
+            if (Number.isInteger(port) && port > 0)
+                ports.add(port);
+        }
+        catch {
+        }
+    };
+    for (const e of endpoints) {
+        if (e.probe.kind === "tcp")
+            ports.add(e.probe.port);
+        else if (e.probe.kind === "http")
+            fromUrl(e.probe.url);
+        fromUrl(e.url);
+    }
+    return [...ports].sort((a, b) => a - b);
+}
+export function parseDockerPsPorts(output, ignorePrefix) {
+    const held = new Map();
+    for (const line of output.split("\n")) {
+        const tab = line.indexOf("\t");
+        if (tab < 0)
+            continue;
+        const name = line.slice(0, tab).trim();
+        if (!name || name.startsWith(ignorePrefix))
+            continue;
+        for (const m of line.slice(tab + 1).matchAll(/:(\d+)->\d+\/(?:tcp|udp)/g)) {
+            const port = Number(m[1]);
+            if (!held.has(port))
+                held.set(port, name);
+        }
+    }
+    return held;
+}
+const defaultPortConflictIo = {
+    dockerPs: () => {
+        try {
+            return execFileSync("docker", ["ps", "--format", "{{.Names}}\t{{.Ports}}"], {
+                encoding: "utf-8",
+                stdio: ["ignore", "pipe", "ignore"],
+            });
+        }
+        catch {
+            return "";
+        }
+    },
+    processOn: (port) => {
+        try {
+            const out = execFileSync("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-Fc"], {
+                encoding: "utf-8",
+                stdio: ["ignore", "pipe", "ignore"],
+            });
+            const cmd = out.split("\n").find((l) => l.startsWith("c"));
+            return cmd ? cmd.slice(1) : null;
+        }
+        catch {
+            return null;
+        }
+    },
+    listening: (port) => probeTcp(port, { timeoutMs: 300 }),
+};
+export async function findPortConflicts(ports, ignorePrefix, io = defaultPortConflictIo) {
+    const unique = [...new Set(ports)].sort((a, b) => a - b);
+    const bound = (await Promise.all(unique.map(async (port) => ((await io.listening(port)) ? port : null)))).filter((p) => p !== null);
+    if (bound.length === 0)
+        return [];
+    const containers = parseDockerPsPorts(io.dockerPs(), ignorePrefix);
+    return bound.map((port) => {
+        const container = containers.get(port);
+        if (container)
+            return { port, holder: { kind: "container", name: container } };
+        const process = io.processOn(port);
+        return { port, holder: process ? { kind: "process", name: process } : null };
+    });
+}
+export function describePortConflicts(conflicts, moveHints = new Map()) {
+    const lines = conflicts.flatMap(({ port, holder }) => {
+        const remedy = holder?.kind === "container"
+            ? `docker stop ${holder.name}`
+            : `lsof -nP -iTCP:${port} -sTCP:LISTEN, then stop what it names`;
+        const what = holder ? `held by ${holder.kind} ${holder.name}` : "held by something lsof would not name";
+        const move = moveHints.get(port);
+        return move
+            ? [`  ${String(port).padEnd(5)} ${what.padEnd(38)} (${remedy})`, `  ${"".padEnd(5)} or: ${move}`]
+            : [`  ${String(port).padEnd(5)} ${what.padEnd(38)} (${remedy})`];
+    });
+    return (`Cannot start the local platform — ${conflicts.length === 1 ? "a host port it needs is" : "host ports it needs are"} already in use:\n` +
+        lines.join("\n") +
+        '\nStop what holds the port (or move it), then run mesh start again. A port lost this way does not fail as "port in use": the container never joins the network and a later service reports an unrelated error.' +
+        "\nIf the port is held by something you cannot stop and the stack can live without it: mesh start --skip-port-check");
+}

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

@@ -6,4 +6,5 @@ export interface WaitForStackIo {
     overlayServices: () => ReadonlySet<string>;
 }
 export declare function waitForStack(io?: WaitForStackIo): Promise<void>;
+export declare function startHereLines(hubRunning: boolean, up?: ReadonlyMap<string, boolean>): string[];
 export declare function registerLocalCommands(program: Command): void;

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

@@ -3,13 +3,14 @@ import * as path from "path";
 import chalk from "chalk";
 import { logError, logInfo, logSuccess, logWarn } from "../../utils/log.js";
 import { MeshCliError } from "../../utils/errors.js";
-import { COMPOSE_PROJECT, DEFAULT_HUB_PORT, ONE_SHOT_SERVICES, STACK_ENDPOINTS, compose, composeStreamed, crashedServices, ensureDockerAvailable, findPackageRoot, hubApiRunning, hubEndpoints, hubOverlayRunning, hubOverlayServices, hubPort, probeEndpoint, stackOwnedElsewhere, stackServices, } from "./stack.js";
+import { compose, COMPOSE_PROJECT, composeStreamed, crashedServices, DEFAULT_HUB_PORT, ensureDockerAvailable, findPackageRoot, hubApiRunning, hubEndpoints, hubOverlayRunning, hubOverlayServices, hubPort, ONE_SHOT_SERVICES, probeEndpoint, STACK_ENDPOINTS, stackOwnedElsewhere, stackServices, } from "./stack.js";
 import { probeRegistryToken, REGISTRY_LOGIN_FIX } from "../../utils/auth-preflight.js";
 import { ensureHubAuthImage, ensureHubImages, buildHubImagesFromSource, readHubCompiledAuthz, hasRegistryAuth, localHubVersion, planWithHubRefresh, } from "./hub-local.js";
 import { reconcileRegistryFromZitadel } from "./auth-provision.js";
 import { LOCAL_AWS_CONFIG, localAwsEnv, seedLocalPlatform, verifyFabric } from "./seed.js";
 import { LOGIN_CONTEXT, readHubAuth, seedZitadel, TEST_USERS } from "./seed-zitadel.js";
 import { publishHubAuthzCatalog } from "./seed-hub-catalog.js";
+import { describePortConflicts, findPortConflicts, hostPortsOf } from "./helpers.js";
 const WAIT_TIMEOUT_MS = 180_000;
 const WAIT_POLL_MS = 3_000;
 function crashError(crashed) {
@@ -85,8 +86,33 @@ function printEndpoints(hubRunning) {
     console.log(chalk.bold("Login"));
     console.log(`  mesh login ${LOGIN_CONTEXT}`);
     console.log(`  ${chalk.dim(`test users: ${TEST_USERS.map((u) => u.email).join(", ")} (password: ${TEST_USERS[0].password})`)}`);
-    console.log("");
-    logInfo("Next: `mesh dev` in an apps repo wires services to this stack automatically.");
+    printStartHere(hubRunning);
+}
+export function startHereLines(hubRunning, up) {
+    const dev = TEST_USERS[0];
+    const mailbox = STACK_ENDPOINTS.find((e) => e.service === "mailpit");
+    const flag = (service) => up?.get(service) === false ? chalk.red("  (not responding — see Endpoints below)") : "";
+    const lines = ["", chalk.bold.cyan("★ Start here")];
+    if (hubRunning) {
+        lines.push(`  ${"Hub".padEnd(10)} ${chalk.bold.cyan(`http://localhost:${hubPort()}`)}${flag("hub-ui")}`, `  ${"".padEnd(10)} ${chalk.dim(`sign in as ${dev.email} / ${dev.password} — an account already exists; do not Register`)}`);
+    }
+    if (mailbox) {
+        lines.push(`  ${"Mailbox".padEnd(10)} ${chalk.cyan(mailbox.url)}${flag("mailpit")}`, `  ${"".padEnd(10)} ${chalk.dim("every email the local platform sends (sign-up, verification, password reset) lands here — nothing leaves your machine")}`);
+    }
+    lines.push(`  ${"Your app".padEnd(10)} ${chalk.cyan("cd apps/<name> && mesh dev")}   ${chalk.dim("no app yet? mesh create-app")}`, `  ${"Check-up".padEnd(10)} ${chalk.cyan("mesh status")}`, "");
+    return lines;
+}
+function printStartHere(hubRunning, up) {
+    for (const line of startHereLines(hubRunning, up))
+        console.log(line);
+}
+function portMoveHints() {
+    return new Map([
+        [
+            Number(hubPort()),
+            "MESH_HUB_PORT=<free port> mesh start   (or mesh start --no-hub, which starts everything else)",
+        ],
+    ]);
 }
 function repoRootForHubSource() {
     for (let dir = process.cwd();;) {
@@ -108,6 +134,7 @@ export function registerLocalCommands(program) {
         .option("--with-hub", "force-refresh the Hub to the latest published @mesh-tech/hub (the Hub is included by default when its images exist or registry auth is available)")
         .option("--hub-from-source", "build the Hub images from THIS checkout's apps/hub instead of the published tarball (the only way to exercise a Hub change locally)")
         .option("--takeover", "re-own a stack that another checkout started (may recreate shared containers with THIS checkout's config)", false)
+        .option("--skip-port-check", "start even though a host port the stack wants is already held (the service that loses the bind will be broken — use when the holder is something you cannot stop)", false)
         .action(async (opts) => {
         ensureDockerAvailable();
         const foreign = stackOwnedElsewhere();
@@ -123,6 +150,15 @@ export function registerLocalCommands(program) {
         if (foreign && opts.takeover) {
             logWarn(`Taking over the running stack (previously driven from ${foreign}).`);
         }
+        if (!opts.skipPortCheck && !stackServices().some((s) => s.state === "running")) {
+            const ports = hostPortsOf([...STACK_ENDPOINTS, ...(opts.hub ? hubEndpoints() : [])]);
+            const conflicts = await findPortConflicts(ports, `${COMPOSE_PROJECT}-`);
+            if (conflicts.length > 0) {
+                throw new MeshCliError(describePortConflicts(conflicts, portMoveHints()), {
+                    remediation: { command: "mesh start   # once the port is free" },
+                });
+            }
+        }
         let hubVersion;
         if (opts.hub) {
             if (opts.hubFromSource) {
@@ -307,6 +343,7 @@ export function registerLocalCommands(program) {
                 process.exitCode = 1;
             return;
         }
+        printStartHere(hasHub, new Map(probes.map((p) => [p.service, p.up])));
         console.log(chalk.bold("Containers"));
         for (const service of services) {
             const ok = service.state === "running" &&

package/dist/src/commands/login.d.ts

@@ -35,6 +35,7 @@ export declare function atomicWriteFileSync(path: string, data: string, mode: nu
 declare function clearCredentials(context: string): void;
 declare function decodeJwtPayload(token: string): Record<string, unknown>;
 export declare function deviceLoginWithReissue(attempt: (codeNumber: number) => Promise<"success" | "expired">, maxCodes?: number): Promise<void>;
+export declare function loginTimeoutMessage(context: string): string;
 export declare function isRemoteEnvironment(): boolean;
 export interface StatusLine {
     level: "success" | "info" | "warn";

package/dist/src/commands/login.js

@@ -362,7 +362,7 @@ function login(context, config) {
         });
         timeoutId = setTimeout(() => {
             teardown();
-            reject(new Error("Login timed out (2 minutes)"));
+            reject(new Error(loginTimeoutMessage(context)));
         }, 120_000);
     });
 }
@@ -465,6 +465,13 @@ async function attemptDeviceCode(context, config) {
     }
     return "expired";
 }
+export function loginTimeoutMessage(context) {
+    const base = "Login timed out (2 minutes)";
+    if (context !== "local")
+        return base;
+    return (`${base}. The local platform already has a signed-up user — sign in as dev@local.mesh / LocalDev1! instead of registering. ` +
+        "If you did register, its confirmation email is in the local mailbox at http://localhost:8025; confirm it there and run the command again.");
+}
 export function isRemoteEnvironment() {
     if (process.env.REMOTE_CONTAINERS || process.env.CODESPACES)
         return true;

package/dist/src/commands/temporal.js

@@ -532,7 +532,11 @@ var init_src = __esm({
       description: z.string().optional(),
       surfaces: apiSurfaceSchema,
       credentials: z.object({ keyedBy: z.string().nullish() }).optional(),
-      docs: z.object({ url: z.string().min(1), contentHash: z.string().min(1) }),
+      docs: z.object({
+        url: z.string().min(1),
+        contentHash: z.string().min(1),
+        siteUrl: z.string().min(1).optional()
+      }),
       enabledOps: z.array(z.string()),
       // The consumer schema strips unknown keys, so a producer-side field that is
       // not mirrored here never reaches a consumer — mirror every addition.
@@ -1083,7 +1087,7 @@ ${url}`);
     });
     timeoutId = setTimeout(() => {
       teardown();
-      reject(new Error("Login timed out (2 minutes)"));
+      reject(new Error(loginTimeoutMessage(context)));
     }, 12e4);
   });
 }
@@ -1187,6 +1191,11 @@ async function attemptDeviceCode(context, config) {
   }
   return "expired";
 }
+function loginTimeoutMessage(context) {
+  const base = "Login timed out (2 minutes)";
+  if (context !== "local") return base;
+  return `${base}. The local platform already has a signed-up user \u2014 sign in as dev@local.mesh / LocalDev1! instead of registering. If you did register, its confirmation email is in the local mailbox at http://localhost:8025; confirm it there and run the command again.`;
+}
 function isRemoteEnvironment() {
   if (process.env.REMOTE_CONTAINERS || process.env.CODESPACES) return true;
   if (fs2.existsSync("/.dockerenv")) return true;