@mesh-tech/mesh-cli 0.27.0 → 0.28.0

package/dist/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "5b8435e57",
-  "builtAt": "2026-09-17T20:26:45.360Z"
+  "commit": "dd1a85628",
+  "builtAt": "2026-09-17T22:16:24.040Z"
 }

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

@@ -23,7 +23,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: {

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

@@ -145,7 +145,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.28.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.18.0",
     "@mesh-tech/workflow-viz": "0.3.0",
     "@tanstack/intent": "^0.3.6",
     "@types/node": "^20.0.0",

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). */

package/templates/external-service/index.ts.hbs

@@ -42,7 +42,11 @@ const vendorpay = new mesh.apps.ExternalService("vendorpay", {
   env,
   type: "payment",
   kind: "connection",
-  description: "Example payments vendor (quotes API) — the external-service pattern",
+  // One sentence a client operator can act on, in their words. This renders on
+  // the Hub's Integrations row, which a credit union's own staff read.
+  description: "Gets price quotes from our payments vendor.",
+  // Engineer to engineer: never serialized by a Hub deployed for a client.
+  operatorNote: "Example vendor wired the external-service way — credentials in Secrets Manager, no runtime to probe.",
   credentials: {
     fields: {
       baseUrl: { name: "Base URL", description: "Vendor API endpoint" },

package/templates/platform-repo/AGENTS.md.hbs

@@ -3,11 +3,27 @@
 - Invoke the CLI as `pnpm mesh <cmd>` or (cwd-independent) `pnpm exec mesh <cmd>` —
   a root `"mesh"` script + the `@mesh-tech/mesh-cli` devDependency make both work
   after `pnpm install`. For a bare `mesh` on PATH, run once: `pnpm exec mesh install-shim`.
-- Operations are `mesh` commands, never raw `aws`/`pulumi`/`kubectl`:
-  `mesh login {{tenant}}.{{env}}`, `mesh deploy preview|up` (run inside
-  `core/` or `platform/`), `mesh init app-tenant` (doctor).
+- Operations are `mesh` commands, never raw `pulumi`/`kubectl`: `mesh deploy
+  preview|up` (run inside `core/` or `platform/`), `mesh init app-tenant`
+  (doctor). **One exception:** a platform stack carries no `mesh:deployerRole`
+  — only app stacks do — so `mesh deploy` reads credentials from the
+  environment, on the first deploy and on every day-2 run:
+  `aws sso login --profile {{profile}}`, then
+  `eval "$(aws configure export-credentials --profile {{profile}} --format env)"`.
+- **`mesh login {{tenant}}.{{env}}` comes LAST, after the first deploy.** The
+  Zitadel it signs in to is what the `platform/` layer creates; run earlier it
+  fails with `No configuration found for "{{tenant}}.{{env}}"`. Package access
+  is a separate, global sign-in (`mesh registry login`) and is not needed in
+  this repo at all.
 - Deploy order matters: `core/` before `platform/` (platform imports core
-  from the SSM registry).
+  from the SSM registry), and the NS delegation of the public zone is a manual
+  step **in the middle of the `core/` deploy** — that deploy blocks on its ACM
+  certificate until you delegate the new zone's NS records from the parent, so
+  a `core/` deploy that looks hung is waiting on you. README.md holds the full
+  first-deploy sequence, the one `mesh init` printed when it scaffolded this
+  repo. Do not invent a different one.
+- `platform/` builds service images, so it needs Docker; `core/` does not.
+  That is why a Docker-less container can deploy `core/` and stop there.
 - Capabilities are config, not code: enable/disable platform services in
   `platform/Pulumi.{{tenant}}-{{env}}.yaml` (temporal/zitadel/hub/tenants/…);
   the `index.ts` layer programs should rarely change.

package/templates/workflow/index.ts.hbs

@@ -64,5 +64,9 @@ const worker = new mesh.apps.TemporalWorker("worker", {
 // --- Outputs ---
 
 export const app = env.register({
-  description: "{{titleCase name}} — Temporal workflow app",
+  displayName: "{{titleCase name}}",
+  // What a client operator reads on the Apps list. One sentence, their words.
+  description: "Runs {{titleCase name}}'s scheduled and long-running jobs.",
+  // Engineer to engineer; a Hub deployed for a client never serializes it.
+  operatorNote: "Temporal workflow app scaffolded by `mesh create-app --template workflow`.",
 });