@mesh-tech/mesh-cli 0.27.0 → 0.29.0

package/dist/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "5b8435e57",
-  "builtAt": "2026-09-17T20:26:45.360Z"
+  "commit": "0c55ee89e",
+  "builtAt": "2026-09-18T16:46:53.074Z"
 }

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

@@ -0,0 +1,28 @@
+export interface ProbeResult {
+    findings: UnresolvedImport[];
+    unchecked: string | null;
+}
+export interface UnresolvedImport {
+    pkg: string;
+    specifier: string;
+    file: string;
+    importer: string;
+    via: string[];
+    fix: string;
+}
+export declare function stripComments(source: string): string;
+export declare function moduleSpecifiers(source: string): string[];
+export declare function splitSpecifier(specifier: string): {
+    pkg: string;
+    sub: string;
+} | null;
+export declare function findPackageDir(fromDir: string, pkg: string): string | null;
+export declare function resolveSubpath(pkgDir: string, sub: string): string | null;
+export declare function programEntry(appDir: string): string | null;
+export declare function dependenciesInstalled(dir: string, stopAt?: string): boolean;
+export interface ProbeOptions {
+    entry?: string;
+    label?: string;
+    root?: string;
+}
+export declare function resolveProgramImports(appDir: string, options?: ProbeOptions): ProbeResult;

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

@@ -0,0 +1,276 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { builtinModules } from "node:module";
+import { parse as parseYaml } from "yaml";
+const CONDITIONS = new Set(["source", "node", "import", "require", "module", "module-sync", "default"]);
+const EXTENSIONS = ["", ".ts", ".tsx", ".js", ".mjs", ".cjs", "/index.ts", "/index.js", "/index.mjs"];
+const SCOPE = "@mesh-tech/";
+const FILE_BUDGET = 1500;
+const BUILTINS = new Set(builtinModules);
+export function stripComments(source) {
+    return source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:"'`\\])\/\/[^\n]*/g, "$1");
+}
+export function moduleSpecifiers(source) {
+    const text = stripComments(source);
+    const out = [];
+    for (const m of text.matchAll(/(?<![.\w$])(?:import|export)\b([^;]*?)\bfrom\s*["']([^"']+)["']/g)) {
+        if (/^\s*type\s/.test(m[1] ?? ""))
+            continue;
+        out.push(m[2] ?? "");
+    }
+    for (const m of text.matchAll(/(?<![.\w$])import\s*["']([^"']+)["']/g))
+        out.push(m[1] ?? "");
+    for (const m of text.matchAll(/(?<![.\w$])import\s*\(\s*["']([^"']+)["']\s*\)/g))
+        out.push(m[1] ?? "");
+    for (const m of text.matchAll(/(?<![.\w$])require\s*\(\s*["']([^"']+)["']\s*\)/g))
+        out.push(m[1] ?? "");
+    return [...new Set(out)].filter(Boolean);
+}
+export function splitSpecifier(specifier) {
+    if (!specifier || specifier.startsWith(".") || specifier.startsWith("/") || specifier.startsWith("#"))
+        return null;
+    if (specifier.includes(":"))
+        return null;
+    if (BUILTINS.has(specifier))
+        return null;
+    const parts = specifier.split("/");
+    const depth = specifier.startsWith("@") ? 2 : 1;
+    if (parts.length < depth || parts.some((p) => p === ""))
+        return null;
+    const pkg = parts.slice(0, depth).join("/");
+    const rest = parts.slice(depth);
+    return { pkg, sub: rest.length > 0 ? `./${rest.join("/")}` : "." };
+}
+export function findPackageDir(fromDir, pkg) {
+    let dir = path.resolve(fromDir);
+    for (;;) {
+        const candidate = path.join(dir, "node_modules", ...pkg.split("/"));
+        if (fs.existsSync(path.join(candidate, "package.json"))) {
+            try {
+                return fs.realpathSync(candidate);
+            }
+            catch {
+                return candidate;
+            }
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+function conditionTargets(node, acc = []) {
+    if (typeof node === "string") {
+        acc.push(node);
+        return acc;
+    }
+    if (Array.isArray(node)) {
+        for (const entry of node)
+            conditionTargets(entry, acc);
+        return acc;
+    }
+    if (!node || typeof node !== "object")
+        return acc;
+    for (const [key, value] of Object.entries(node)) {
+        if (!CONDITIONS.has(key))
+            continue;
+        conditionTargets(value, acc);
+    }
+    return acc;
+}
+function exportTargets(exportsField, sub) {
+    if (typeof exportsField === "string")
+        return sub === "." ? [exportsField] : [];
+    if (Array.isArray(exportsField))
+        return exportsField.flatMap((entry) => exportTargets(entry, sub));
+    if (!exportsField || typeof exportsField !== "object")
+        return [];
+    const map = exportsField;
+    const keys = Object.keys(map);
+    if (keys.length > 0 && !keys.some((k) => k.startsWith(".")))
+        return sub === "." ? conditionTargets(map) : [];
+    if (sub in map)
+        return conditionTargets(map[sub]);
+    let best = [];
+    let bestPrefix = -1;
+    for (const key of keys) {
+        const star = key.indexOf("*");
+        if (star === -1)
+            continue;
+        const prefix = key.slice(0, star);
+        const suffix = key.slice(star + 1);
+        if (sub.length < prefix.length + suffix.length)
+            continue;
+        if (!sub.startsWith(prefix) || !sub.endsWith(suffix))
+            continue;
+        if (prefix.length <= bestPrefix)
+            continue;
+        const segment = sub.slice(prefix.length, sub.length - suffix.length);
+        bestPrefix = prefix.length;
+        best = conditionTargets(map[key]).map((target) => target.replaceAll("*", segment));
+    }
+    return best;
+}
+function isDirectory(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function firstFile(base) {
+    for (const ext of EXTENSIONS) {
+        const candidate = base + ext;
+        try {
+            if (fs.statSync(candidate).isFile())
+                return candidate;
+        }
+        catch {
+        }
+    }
+    return null;
+}
+export function resolveSubpath(pkgDir, sub) {
+    let manifest = {};
+    try {
+        manifest = JSON.parse(fs.readFileSync(path.join(pkgDir, "package.json"), "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (manifest.exports !== undefined) {
+        for (const target of exportTargets(manifest.exports, sub)) {
+            const file = firstFile(path.resolve(pkgDir, target));
+            if (file)
+                return file;
+        }
+        return null;
+    }
+    if (sub === ".")
+        return firstFile(path.resolve(pkgDir, manifest.main ?? "index.js"));
+    return firstFile(path.resolve(pkgDir, sub));
+}
+export function programEntry(appDir) {
+    const app = path.resolve(appDir);
+    const index = path.join(app, "index.ts");
+    if (fs.existsSync(index))
+        return index;
+    let main;
+    try {
+        main = parseYaml(fs.readFileSync(path.join(app, "Pulumi.yaml"), "utf8"))?.main;
+    }
+    catch {
+        return null;
+    }
+    if (typeof main !== "string" || !main)
+        return null;
+    const target = path.resolve(app, main);
+    return isDirectory(target) ? firstFile(path.join(target, "index")) : firstFile(target);
+}
+export function dependenciesInstalled(dir, stopAt) {
+    const root = stopAt === undefined ? null : path.resolve(stopAt);
+    let at = path.resolve(dir);
+    for (;;) {
+        if (fs.existsSync(path.join(at, "node_modules")))
+            return true;
+        if (at === root)
+            return false;
+        const parent = path.dirname(at);
+        if (parent === at)
+            return false;
+        at = parent;
+    }
+}
+function suggestedRange(appDir, parentDir) {
+    try {
+        const manifest = JSON.parse(fs.readFileSync(path.join(appDir, "package.json"), "utf8"));
+        for (const section of [manifest.dependencies, manifest.devDependencies]) {
+            for (const [name, range] of Object.entries(section ?? {})) {
+                if (name.startsWith(SCOPE) && range)
+                    return range;
+            }
+        }
+    }
+    catch {
+    }
+    if (!parentDir)
+        return null;
+    try {
+        const version = JSON.parse(fs.readFileSync(path.join(parentDir, "package.json"), "utf8")).version;
+        return version ? `^${version}` : null;
+    }
+    catch {
+        return null;
+    }
+}
+function displayPath(app, visit) {
+    const within = path.relative(visit.pkg === null ? app : visit.pkgDir, visit.file).split(path.sep).join("/");
+    return visit.pkg === null ? within : `${visit.pkg}/${within}`;
+}
+export function resolveProgramImports(appDir, options = {}) {
+    const app = path.resolve(appDir);
+    const label = options.label ?? path.basename(app);
+    const entryFile = options.entry ? firstFile(path.resolve(app, options.entry)) : programEntry(app);
+    if (!dependenciesInstalled(app, options.root)) {
+        return { findings: [], unchecked: "dependencies are not installed (run the install, then re-run)" };
+    }
+    if (!entryFile) {
+        return { findings: [], unchecked: "no Pulumi program found (index.ts, or the file Pulumi.yaml's `main` names)" };
+    }
+    const findings = [];
+    const reported = new Set();
+    const seen = new Set([entryFile]);
+    const queue = [{ file: entryFile, pkgDir: app, pkg: null, via: [] }];
+    let budget = FILE_BUDGET;
+    while (queue.length > 0 && budget-- > 0) {
+        const here = queue.shift();
+        let source;
+        try {
+            source = fs.readFileSync(here.file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const fromDir = path.dirname(here.file);
+        for (const specifier of moduleSpecifiers(source)) {
+            if (specifier.startsWith(".")) {
+                if (here.pkg === null)
+                    continue;
+                const next = firstFile(path.resolve(fromDir, specifier));
+                if (next && !seen.has(next) && next.startsWith(here.pkgDir)) {
+                    seen.add(next);
+                    queue.push({ ...here, file: next });
+                }
+                continue;
+            }
+            const split = splitSpecifier(specifier);
+            if (!split)
+                continue;
+            const inScope = split.pkg.startsWith(SCOPE);
+            if (here.pkg !== null && !inScope)
+                continue;
+            const pkgDir = findPackageDir(fromDir, split.pkg);
+            const target = pkgDir ? resolveSubpath(pkgDir, split.sub) : null;
+            if (!pkgDir || !target) {
+                if (reported.has(specifier))
+                    continue;
+                reported.add(specifier);
+                const range = inScope ? suggestedRange(app, here.pkg === null ? null : here.pkgDir) : null;
+                const line = `"${split.pkg}": "${range ?? (inScope ? "<the version your other @mesh-tech packages use>" : "<the version you need>")}"`;
+                const fix = pkgDir
+                    ? `${split.pkg} is installed but ships no ${split.sub} — the installed version predates the subpath; raise ${line} in ${label}/package.json`
+                    : `add ${line} to ${label}/package.json dependencies`;
+                findings.push({ pkg: split.pkg, specifier, file: here.file, importer: displayPath(app, here), via: here.via, fix });
+                continue;
+            }
+            if (!inScope || seen.has(target))
+                continue;
+            seen.add(target);
+            queue.push({ file: target, pkgDir, pkg: split.pkg, via: [...here.via, specifier] });
+        }
+    }
+    findings.sort((a, b) => a.pkg.localeCompare(b.pkg) || a.specifier.localeCompare(b.specifier));
+    const unchecked = queue.length > 0 ? `the import graph exceeded ${FILE_BUDGET} files` : null;
+    return { findings, unchecked };
+}

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

@@ -1,6 +1,7 @@
 import { Command } from "commander";
+import { type ProbeResult } from "./app-check-resolve.js";
 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" | "DOCS_SITE_PUBLIC" | "DOCS_AUDIENCE_IMPLICIT" | "DOCS_AUDIENCE_UNGRANTABLE" | "DOCS_VENDOR_AUDIENCE_PARTNER";
+export type AppCheckCode = "UNRESOLVABLE_IMPORT" | "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_PUBLIC" | "DOCS_AUDIENCE_IMPLICIT" | "DOCS_AUDIENCE_UNGRANTABLE" | "DOCS_VENDOR_AUDIENCE_PARTNER";
 export interface AppCheckRule {
     gate: string;
     title: string;
@@ -35,14 +36,16 @@ export declare function docsSiteFindings(text: string): Array<{
 }>;
 export declare function statedKind(decl: Pick<SurfaceDeclaration, "ctor">, args: Map<string, string>): string | undefined;
 export declare function listApps(root: string): string[];
-export declare function scanApp(root: string, appRel: string): Finding[];
+export declare function probeResolution(root: string, appRel: string): ProbeResult;
+export declare function scanApp(root: string, appRel: string, resolution?: ProbeResult): Finding[];
 export declare function scanRepo(root: string): Finding[];
 export interface AppCheckContext {
     root: string;
     app: string | null;
     findings: Finding[];
+    unchecked: string | null;
 }
-export declare function resultFor(code: AppCheckCode, findings: Finding[]): CheckResult;
+export declare function resultFor(code: AppCheckCode, findings: Finding[], unchecked?: string | null): CheckResult;
 export declare function appContractChecks(scope: "app" | "repo"): Check<AppCheckContext>[];
 export interface AppCheckReport {
     root: string;

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

@@ -3,8 +3,17 @@ import * as path from "node:path";
 import { logError, logInfo } from "../utils/index.js";
 import { MeshCliError, emitJsonPayload } from "../utils/errors.js";
 import { resolveTargetRoot } from "./skills.js";
+import { programEntry, resolveProgramImports } from "./app-check-resolve.js";
 import { ICONS, aggregateStatus, jsonReport, renderHuman, runChecks, } from "./dev-doctor.js";
 export const APP_CHECK_RULES = {
+    UNRESOLVABLE_IMPORT: {
+        gate: "0.6",
+        title: "The Pulumi program's imports resolve",
+        severity: "block",
+        remediation: "declare the package in apps/<app>/package.json dependencies, at the range the app's other @mesh-tech/* packages use, and re-install — " +
+            "an optional peer that nothing names installs silently and fails at `mesh deploy`",
+        scope: "app",
+    },
     UI_IN_API: {
         gate: "0.1",
         title: "UI is its own service",
@@ -23,7 +32,8 @@ export const APP_CHECK_RULES = {
         gate: "0.2",
         title: "App registers with the Hub",
         severity: "block",
-        remediation: "end index.ts with `export const app = env.register({ description })`",
+        remediation: "end index.ts with `export const app = env.register({ displayName, description })` — " +
+            "one sentence a non-technical operator can act on; put the caveats in `operatorNote`",
         scope: "app",
     },
     CUSTOM_SESSION_AUTH: {
@@ -609,7 +619,10 @@ export function listApps(root) {
         apps.push(".");
     return apps;
 }
-export function scanApp(root, appRel) {
+export function probeResolution(root, appRel) {
+    return resolveProgramImports(path.resolve(root, appRel), { root, label: appRel === "." ? "this app" : appRel });
+}
+export function scanApp(root, appRel, resolution = probeResolution(root, appRel)) {
     const app = path.resolve(root, appRel);
     const index = path.join(app, "index.ts");
     const findings = [];
@@ -619,6 +632,12 @@ export function scanApp(root, appRel) {
     const hasProgram = fs.existsSync(index) || fs.existsSync(path.join(app, "Pulumi.yaml"));
     if (!hasProgram)
         return findings;
+    const entry = programEntry(app);
+    for (const bad of resolution.findings) {
+        const chain = [...bad.via, bad.specifier].join(" → ");
+        const at = rel(root, entry ?? index);
+        hit("UNRESOLVABLE_IMPORT", at, `${chain} does not resolve from this app (imported by ${bad.importer}) — ${bad.fix}`);
+    }
     if (fs.existsSync(index)) {
         const indexRel = rel(root, index);
         let servesHtml = false;
@@ -727,9 +746,12 @@ export function scanRepo(root) {
     }
     return findings;
 }
-export function resultFor(code, findings) {
+export function resultFor(code, findings, unchecked = null) {
     const rule = APP_CHECK_RULES[code];
     const mine = findings.filter((f) => f.code === code);
+    if (code === "UNRESOLVABLE_IMPORT" && unchecked) {
+        return { status: "ok", summary: `gate ${rule.gate}: not checked — ${unchecked}` };
+    }
     if (mine.length === 0)
         return { status: "ok", summary: `gate ${rule.gate}: no ${code} finding` };
     return {
@@ -744,7 +766,7 @@ export function appContractChecks(scope) {
         id: code,
         title: `${APP_CHECK_RULES[code].title} (${APP_CHECK_RULES[code].gate})`,
         phases: ["ondemand", "preflight"],
-        run: async (ctx) => resultFor(code, ctx.findings),
+        run: async (ctx) => resultFor(code, ctx.findings, ctx.unchecked),
     }));
 }
 export async function runAppCheck(root, apps) {
@@ -757,10 +779,12 @@ export async function runAppCheck(root, apps) {
     }
     const scopes = [];
     for (const app of targets) {
-        const results = await runChecks({ root, app, findings: scanApp(root, app) }, "ondemand", appContractChecks("app"));
+        const resolution = probeResolution(root, app);
+        const ctx = { root, app, findings: scanApp(root, app, resolution), unchecked: resolution.unchecked };
+        const results = await runChecks(ctx, "ondemand", appContractChecks("app"));
         scopes.push({ scope: app, ...jsonReport(results) });
     }
-    const repoResults = await runChecks({ root, app: null, findings: scanRepo(root) }, "ondemand", appContractChecks("repo"));
+    const repoResults = await runChecks({ root, app: null, findings: scanRepo(root), unchecked: null }, "ondemand", appContractChecks("repo"));
     scopes.push({ scope: "(repo)", ...jsonReport(repoResults) });
     return { root, status: aggregateStatus(scopes.map((s) => ({ status: s.status, summary: "" }))), scopes };
 }
@@ -786,7 +810,7 @@ export function registerAppCommands(program) {
     const app = program.command("app").description("Inspect a tenant app against the Mesh app contract");
     app
         .command("check")
-        .description("Check tenant apps against the Mesh app contract (@mesh-tech/app-kit skills/apps/references/app-contract.md): a UI is its own service, the app registers with the Hub, sign-in goes through the platform proxy, logs go through @mesh-tech/logger, and people/roles/keys are surfaced through the Hub. Exit 1 on any blocking finding — the same gate mesh create-app, tenant CI and the platform reviewer run.")
+        .description("Check tenant apps against the Mesh app contract (@mesh-tech/app-kit skills/apps/references/app-contract.md): a UI is its own service, the app registers with the Hub, sign-in goes through the platform proxy, logs go through @mesh-tech/logger, people/roles/keys are surfaced through the Hub, and the Pulumi program's imports resolve from the app directory. Exit 1 on any blocking finding — the same gate mesh create-app, tenant CI and the platform reviewer run. The import gate reads the installed dependency tree, so run it after the install; with no node_modules it reports itself not checked rather than met.")
         .argument("[apps...]", "repo-relative app dirs to check (default: every apps/* with a Pulumi program)")
         .option("--root <dir>", "checkout to scan (default: the enclosing git root)")
         .option("--json", "machine-readable output (one report per app plus the repo-scoped checks)", false)

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

@@ -19,7 +19,9 @@ export interface HubDevEnvOptions {
     tenants?: string;
     uiPort: number;
     apiPort: number;
+    audience?: string;
 }
+export declare function resolveHubAudience(raw: string | undefined): "operator" | "tenant";
 export interface AssembledHubEnv {
     apiEnv: Record<string, string>;
     uiEnv: Record<string, string>;

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

@@ -99,6 +99,11 @@ export function forwardedSessionVars(sessionEnv) {
     }
     return out;
 }
+export function resolveHubAudience(raw) {
+    if (raw === undefined || raw === "")
+        return "operator";
+    return raw.trim().toLowerCase() === "operator" ? "operator" : "tenant";
+}
 export function assembleHubEnv(session, sessionEnv, opts) {
     const warnings = [];
     const notes = [];
@@ -141,6 +146,7 @@ export function assembleHubEnv(session, sessionEnv, opts) {
     if (!temporalAddress) {
         throw new MeshCliError(`Dev session '${session.name}' exposes no Temporal tunnel — the Hub can't reach the stack's Temporal.`, { remediation: { command: "mesh dev  # relaunch; the session records tunnels.temporal in its state" } });
     }
+    const audienceEnv = { HUB_AUDIENCE: resolveHubAudience(opts.audience) };
     const apiEnv = {
         ...forwarded,
         PORT: String(opts.apiPort),
@@ -148,6 +154,7 @@ export function assembleHubEnv(session, sessionEnv, opts) {
         HUB_TENANT: hubTenant,
         HUB_SCOPE_ENV: scopeEnv,
         HUB_SCOPE_TENANTS: scopeTenants.join(","),
+        ...audienceEnv,
         ...(isLocalPlatform ? localPlatformEnv(sessionEnv) : {}),
     };
     const uiEnv = {
@@ -157,6 +164,7 @@ export function assembleHubEnv(session, sessionEnv, opts) {
         HUB_TENANT: hubTenant,
         DEFAULT_ORG: scopeTenants[0],
         DEFAULT_ENV: scopeEnv,
+        ...audienceEnv,
     };
     return { apiEnv, uiEnv, scope: { hubTenant, scopeEnv, scopeTenants }, temporalAddress, warnings, notes };
 }
@@ -282,7 +290,12 @@ async function hubDevAction(opts) {
         throw new MeshCliError(`Dev session '${session.name}' has a state file but no live tmux session — its tunnels and token-server are gone.`, { remediation: { command: `mesh dev  # from ${session.state.appRoot}` } });
     }
     const sessionEnv = readTmuxSessionEnv(session.name);
-    const assembled = assembleHubEnv(session, sessionEnv, { tenants: opts.tenants, uiPort, apiPort });
+    const assembled = assembleHubEnv(session, sessionEnv, {
+        tenants: opts.tenants,
+        uiPort,
+        apiPort,
+        audience: opts.audience ?? process.env.HUB_AUDIENCE,
+    });
     if (opts.printEnv) {
         console.log(chalk.bold("\nhub-api env:"));
         for (const [k, v] of Object.entries(redactEnv(assembled.apiEnv)))
@@ -308,6 +321,7 @@ async function hubDevAction(opts) {
     logInfo(`Dev session : ${session.name} (${session.state.appRoot})`);
     logInfo(`Hub source  : ${platformDir}`);
     logInfo(`Scope       : HUB_TENANT=${assembled.scope.hubTenant} HUB_SCOPE_ENV=${assembled.scope.scopeEnv} HUB_SCOPE_TENANTS=${assembled.scope.scopeTenants.join(",")}`);
+    logInfo(`Audience    : ${assembled.apiEnv.HUB_AUDIENCE} (--audience tenant for a client's view)`);
     logInfo(`Temporal    : ${assembled.temporalAddress}`);
     for (const note of assembled.notes)
         logInfo(note);
@@ -372,6 +386,7 @@ export function registerHubCommands(program) {
         .description("Launch the current-code Hub (api + ui) against a running `mesh dev` session — env auto-assembled, zero hand-set vars")
         .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 — 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)")

package/fragments/base/index.ts.hbs

@@ -63,6 +63,9 @@ const api = new mesh.apps.Service("api", {
   description: "HTTP API for {{titleCase name}}",
   runtime: "node",
   src: "./api",
+  // Deploying from a machine without Docker (CI container, cloud IDE)?
+  // `buildMode: "remote"` builds the image inside the cluster instead —
+  // see the apps skill: primitives-api → RemoteBuildConfig.
   port: 3000,
   link: [
 {{#if database}}
@@ -145,7 +148,19 @@ new mesh.apps.ApiDocs("docs", {
 // =============================================================================
 
 export const app = env.register({
-  description: "{{titleCase name}}",
+  // The line under this app's name on the Hub's Apps list, read by the
+  // client's own operators more often than by anyone on the team. One
+  // sentence in THEIR words — what it does, not how. No file paths, no ticket
+  // ids, no platform vocabulary; `operatorNote` below is where those go.
+  displayName: "{{titleCase name}}",
+  description: "{{titleCase name}}.",
+  // Engineer to engineer. A Hub deployed for a client never serializes this —
+  // the key is dropped from the response — so it is the right home for the
+  // caveat, the runbook pointer and the ticket.
+  // operatorNote: "Shares a database with the importer; see the runbook.",
+  //
+  // `visibility: "platform"` would hide this app from a client's Hub entirely.
+  // That is for platform components, not for an app a client operates.
 });
 
 // Exported so the bindings above are used, and because a stack's URLs are the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mesh-tech/mesh-cli",
-  "version": "0.27.0",
+  "version": "0.29.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.17.0",
+    "@mesh-tech/tsconfig": "2.20.0",
     "@mesh-tech/workflow-viz": "0.3.0",
     "@tanstack/intent": "^0.3.6",
     "@types/node": "^20.0.0",

package/skills/core/SKILL.md

@@ -97,7 +97,7 @@ Top-level commands (each `register*` is wired in `src/program.ts`, which `bin/me
 | `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 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 read through the Hub rather than on a hostname of its own, with its readers stated and grantable (`DOCS_SITE_PUBLIC` — advisory while the hostname is deprecated — `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`). 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 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 read through the Hub rather than on a hostname of its own, with its readers stated and grantable (`DOCS_SITE_PUBLIC` — advisory while the hostname is deprecated — `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` |
 | `mesh skills` | `sync` | Agent-skill distribution (D1/D2): installs the base building-with-Mesh skills into the repo's `.claude/skills/mesh-*/` (managed-marker files) and wires TanStack-Intent discovery for the pattern skills shipping inside `@mesh-tech/*` packages (`.intent/hooks/` gate + `.claude/settings.json` SessionStart hook + AGENTS.md fence — the PR #2356 mechanism, vendored). Idempotent; runs automatically after `mesh create-app`. | `sync`: `--check` (CI/doctor: exit 1 when missing/stale), `--root <path>` |
 | `mesh docs` | `build`, `portal`, `cli-reference` | `build` builds/validates an **app's** OpenAPI specs from `docs/docs.config.json` (file copy or SymXchange generation). `start`/`stop`/`list` are the simple front door: `start` serves the docs on loopback — DETACHED in a tmux session named `mesh-docs` by default (prints the bare URL once live; `stop` kills the session; `--foreground` or any non-TTY runs in the foreground) — serving the working tree in a mesh-platform checkout, or the published `@mesh-tech/docs` artifact fetched from the role-gated CodeArtifact registry anywhere else (docs version == the @mesh-tech/* baseline it describes; `-v` pins, default latest; cached under `~/.cache/mesh/docs/`). `list` shows the published docs versions. `portal` assembles the **Mesh developer portal** (docs.meshtech.io) from every `docs.json`-opted-in doc root in the repo — a directory publishes its markdown iff it holds a `docs.json`; route/title/order/nav derive from the tree and each file, so adding a doc is adding one file — then hands the assembled tree to Zudoku (`apps/docs/`): default runs `zudoku build`, `--serve` runs `zudoku dev`, `--assemble-only`/`-o` stop after assembly. Links between published files are rewritten to routes; links to unpublished repo files become blob links. Reserved directory names (`plans/`, `designs/`, `incidents/`, … the frozen list in `src/docs/schema.ts`) are excluded at any depth. `cli-reference` regenerates `docs/portal/generated/cli-reference.md` from THIS command tree, so it can't document a flag the binary lacks. `portal --check` is the CI gate (`pnpm check:docs-portal`): docs.json schema validation, reserved-segment fail-close, broken links, and CLI-reference staleness; `--diff-base <ref>` prints the publish-set diff for PR job summaries. Hidden commands and `--version` are excluded from the reference. | `build`: `-c/--config <path>` (default `docs/docs.config.json`); `portal`: `-o/--out <dir>`, `--assemble-only`, `--serve`, `-p/--port <n>` (default `3000`), `--check`, `--print-manifest`, `--diff-base <ref>`, `--manifest-out <path>`; `cli-reference`: `-o/--out <path>`, `--check`; `start`: `-v/--version <v>` (default: latest), `-p/--port <n>` (default `4400`; `0` is foreground-only), `--dev` (foreground HMR), `--foreground`; `stop`: no flags; `list`: no flags |
@@ -154,8 +154,14 @@ mesh init platform acme --domain a-domain-you-control.com   # the only value wit
 - **The NS delegation is a manual step in the middle of the core deploy** —
   the new zone's NS records must be delegated from the parent, or the deploy
   waits on the certificate indefinitely. The printed Next block names it.
-- **The platform layer needs Docker** (it builds service images); the core
-  layer does not. That is why a Docker-less container can deploy core and stop.
+- **The platform layer builds service images with Docker by default**; the
+  core layer never needs it. On a Docker-less seat (a cloud IDE container,
+  some CI runners), set `mesh:buildMode: remote` in the platform stack config
+  — images then build inside the target cluster as rootless-BuildKit Jobs.
+  Three opt-ins still build locally and keep a Docker requirement:
+  `mesh:hub: { cdn: true }` (the UI's CDN asset build), `mesh:headscale` (the
+  VPN join broker image) and `mesh:packageRegistry` (the registry-auth broker
+  image, on unless `broker: false`).
 - Every answer is a flag, so the agent path is one line:
   `mesh init --tenant acme --new-platform dev --domain … --region … --state-bucket … --create-state-bucket --yes`
 

package/templates/api-auth/index.ts.hbs

@@ -115,7 +115,11 @@ new mesh.auth.AppAuthzPointer("authz", { env, mode: "policy-engine", opsHubMetad
 // --- Outputs ---
 
 export const app = env.register({
-  description: "{{titleCase name}} — platform-authenticated API (authn + authz)",
+  displayName: "{{titleCase name}}",
+  // What a client operator reads on the Apps list. One sentence, their words.
+  description: "Serves the {{titleCase name}} API to signed-in callers.",
+  // Engineer to engineer; a Hub deployed for a client never serializes it.
+  operatorNote: "Platform-authenticated API — authn (Zitadel JWT) plus authz (SpiceDB policy engine).",
 });
 
 /** The app's own Zitadel project id (grant people and API keys against this). */

package/templates/api-role-gating/index.ts.hbs

@@ -107,7 +107,11 @@ new mesh.auth.AppAuthzPointer("authz", {
 });
 
 export const app = env.register({
-  description: "{{titleCase name}} — role-gating API (roles enforced in-process from the Zitadel JWT)",
+  displayName: "{{titleCase name}}",
+  // What a client operator reads on the Apps list. One sentence, their words.
+  description: "Serves the {{titleCase name}} API, with access decided by each caller's role.",
+  // Engineer to engineer; a Hub deployed for a client never serializes it.
+  operatorNote: "Role-gating mode — roles are enforced in-process from the Zitadel JWT, no SpiceDB.",
 });
 
 /** The app's own Zitadel project id (grant API keys against this). */