@mesh-tech/mesh-cli 0.15.0 → 0.17.0

package/fragments/service/api/src/index.ts.hbs

@@ -16,12 +16,17 @@
 
 import { Hono } from "hono";
 import { serve } from "@hono/node-server";
+import { createLogger, requestLogger } from "@mesh-tech/logger";
 {{#if temporal}}
 import { createTemporalClient } from "@mesh-tech/app-kit/temporal-client";
 {{/if}}
 
 const PORT = parseInt(process.env.PORT ?? "3000", 10);
+// Every service logs through @mesh-tech/logger (the Mesh app contract, gate
+// 0.4): structured, masked, trace-correlated lines the Hub can search.
+const log = createLogger({ service: "{{name}}-api" });
 const app = new Hono();
+app.use("*", requestLogger(log));
 
 {{#if temporal}}
 const { withClient } = await createTemporalClient();
@@ -51,5 +56,5 @@ app.post("/workflow", async (c) => {
 
 // Start server
 serve({ fetch: app.fetch, port: PORT, hostname: "0.0.0.0" }, (info) => {
-  console.info(`[API] {{titleCase name}} listening on port ${info.port}`);
+  log.info({ port: info.port }, "{{titleCase name}} API listening");
 });

package/fragments/temporal/worker/package.json.hbs

@@ -11,6 +11,7 @@
   },
   "dependencies": {
     "@mesh-tech/app-kit": "{{#if workspaceDeps}}workspace:*{{else}}{{meshRange}}{{/if}}",
+    "@mesh-tech/logger": "{{#if workspaceDeps}}workspace:*{{else}}{{meshRange}}{{/if}}",
     "@temporalio/activity": "^1.11.7",
     "@temporalio/client": "^1.11.7",
     "@temporalio/common": "^1.11.7",

package/fragments/temporal/worker/src/activities.ts.hbs

@@ -3,16 +3,17 @@
  *
  * Activities handle non-deterministic operations:
  * API calls, database queries, external services, etc.
+ *
+ * Log with `log` from @temporalio/activity: it carries the activity context and
+ * reaches the platform logger the worker installs — never the console.
  */
 
+import { log } from "@temporalio/activity";
+
 /**
  * Generate a greeting message
  */
 export async function greet(name: string): Promise<string> {
-  // `console.log` is unstructured: the platform ships worker output to Loki, where
-  // a bare string cannot be filtered by service, activity, or correlation id.
-  // `console.info` is the lint-permitted level; a real activity should use
-  // `@mesh-tech/logger` so its fields are queryable.
-  console.info(`[Activity] Generating greeting for ${name}`);
+  log.info("Generating greeting", { name });
   return `Hello, ${name}!`;
 }

package/fragments/temporal/worker/src/worker.ts.hbs

@@ -6,8 +6,14 @@
  */
 
 import { createTemporalWorker, resolveWorkflows } from "@mesh-tech/app-kit/temporal";
+import { createLogger } from "@mesh-tech/logger";
 import * as activities from "./activities.js";
 
+// The worker process logs through @mesh-tech/logger (the Mesh app contract,
+// gate 0.4). Activities use `log` from @temporalio/activity and workflows `log`
+// from @temporalio/workflow — both route to the Runtime logger app-kit installs.
+const log = createLogger({ service: "{{name}}-worker" });
+
 async function run() {
   const { worker, cleanup } = await createTemporalWorker({
     activities,
@@ -22,6 +28,6 @@ async function run() {
 }
 
 run().catch((err) => {
-  console.error("[Worker] Fatal error:", err);
+  log.error({ err }, "Fatal error");
   process.exit(1);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mesh-tech/mesh-cli",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "CLI for Mesh platform development utilities",
   "type": "module",
   "license": "UNLICENSED",
@@ -30,11 +30,19 @@
       "types": "./dist/src/index.d.ts",
       "default": "./dist/src/index.js"
     },
+    "./temporal": {
+      "types": "./dist/src/commands/temporal.d.ts",
+      "default": "./dist/src/commands/temporal.js"
+    },
+    "./temporal-codec": {
+      "types": "./dist/src/utils/temporal-codec.d.ts",
+      "default": "./dist/src/utils/temporal-codec.js"
+    },
     "./package.json": "./package.json"
   },
   "devDependencies": {
-    "@mesh-tech/tsconfig": "1.53.0",
-    "@mesh-tech/workflow-viz": "0.2.1",
+    "@mesh-tech/tsconfig": "2.0.0",
+    "@mesh-tech/workflow-viz": "0.2.2",
     "@tanstack/intent": "^0.3.6",
     "@types/node": "^20.0.0",
     "tsx": "^4.20.4"
@@ -48,6 +56,7 @@
     "@inquirer/input": "^4.2.1",
     "@inquirer/password": "^4.0.17",
     "@inquirer/select": "^4.3.1",
+    "@mesh-tech/agent-contracts": "0.2.0",
     "@mesh-tech/secrets": "0.1.0",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",

package/skills/core/SKILL.md

@@ -20,8 +20,9 @@ metadata:
 
 # `@mesh-tech/mesh-cli`
 
-Developer CLI for Mesh Platform. Binary name is **`mesh`**. Installed standalone or
-transitively via the app-kit bundle.
+Developer CLI for Mesh Platform. Binary name is **`mesh`**. Install it explicitly —
+`@mesh-tech/app-kit` ships a `mesh` bin shim onto it but declares it an **optional
+peer**, so it is never installed transitively.
 
 ## Running it (MESH-2261)
 
@@ -96,6 +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), 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 (MESH-2479): `--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. 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`; `stop`: `--destroy` (drops volumes/seeds); `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`); a tenant-local auth lib is advisory (`LOCAL_AUTH_LIB`). 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` | `app-tenant` | 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 |
@@ -107,6 +109,8 @@ Top-level commands (each `register*` is wired in `src/program.ts`, which `bin/me
 | `mesh conversations` (alias `conv`) | `list`, `show <id>`, `artifacts <id>` | Read a deployed Mesh agent's conversations: list the caller's conversations, render a transcript, or list a conversation's artifacts. Resolves against the same `agent-targets` registry the MCP `agent_*` tools use. | all three: `--target <name>`, `--api-url <url>` (overrides `--target`), `--context <ctx>` (used with `--api-url`, default `mesh.dev`), `--json` (default when stdout isn't a TTY) |
 | `mesh vpn` | `connect <context>`, `disconnect`, `status`, `tunnel <up\|down\|status>`, `api-key`, `pre-auth-key`, `users` | Headscale VPN mgmt via Tailscale + kubectl. **`connect` now defaults to the userspace `tailscaled`** (brew formula, NOT the GUI Tailscale.app) — the same daemon `mesh dev --transport tailscale` / `mesh vpn tunnel` use, so it **runs headless / under the sandbox** and exposes a local SOCKS5 proxy (route a tool via `ALL_PROXY=socks5://127.0.0.1:<port>`). It relays a one-time browser-register URL for Zitadel auth. `--system` opts into the whole-machine GUI Tailscale.app (system TUN) — needs the app installed and **cannot run headless/sandboxed** (Sparkle.framework abort). For auto-forwarded VPC services (Temporal/RDS) prefer **`mesh vpn tunnel up`** or `mesh dev`. `tunnel status` reports runner **ownership** (`Runner: owned (verified)` vs `NOT OWNED (<reason>)` — a port answering a dial is not proof it's mesh's, MESH-2407); `--json` adds `owned` (bool) + `ownership` (reason string). Admin subcommands `exec` into the `headscale-0` pod. | root: `-t/--tenant` (default `mesh`), `-e/--env` (default `dev`), `-n/--namespace`; `connect`/`disconnect`: `--system`; `tunnel up`: `--context <ctx>`; `tunnel down`: `--stop` (stop daemon, keep login), `--logout`; `tunnel status`: `--json`; `pre-auth-key`: `-u/--user` (**required**), `--expiration <24h>`, `--reusable`, `--ephemeral` |
 | `mesh workflow` | `extract-ir <path>` | Parse Temporal workflow TS source → WorkflowIR graph (nodes+edges). Prints JSON or uploads to S3. | `--app <name>`, `--upload <bucket>` (both required together for S3) |
+| `mesh site` | `publish <name> <dir>`, `versions <name>`, `rollback <name> <version>` | Publish a built directory as an OAuth-protected static site served by Studio, content-addressed and incremental: `publish` walks and hashes the tree, uploads only the blobs the site does not already hold, then commits a version and points the site at it; `versions` lists what has been published, newest first; `rollback` points the site back at an earlier version. Three stateless calls against the agent-api, so a run that dies partway leaves nothing to clean up. | all: `--target <name>`, `--api-url <url>`, `--context <ctx>`; `publish`: `--version-id <id>`, `--no-activate` (publish without pointing the site at it) |
+| `mesh vcs` | `clone <repo> [dest]`, `get <repo> <path>`, `propose`, `rm <repo> <paths...>`, `proposals`/`show`/`diff`/`approve`/`reject`/`comment`/`request-changes`, `drafts <list\|show\|create\|submit\|discard>` | Versioned content repos (`mesh.vcs`). Repos are real git repos over smart HTTP but **read-only** — every change goes through a proposal. `clone` wires the bearer auth header into the clone; `propose` submits the working tree (binary content is base64-encoded from the bytes, not the extension, so images survive intact); **`rm` proposes deletions of files or folders with no clone at all**, and `--dry-run` lists what would go without proposing anything. | all: `--url <base>`, `--token <t>`, `--context <ctx>`; `propose`: `-m/--message`, `--revise <id>`, `--merge-parent <sha>`; `rm`: `-m/--message`, `--dry-run` |
 | `mesh temporal` | `describe <wfId> [runId]`, `history <wfId> [runId]`, `recover-conversation <wfId> [runId]`, `capture-history <wfId> [runId]` | Inspect Temporal workflows for the current app/stack; reconstruct an agent conversation transcript from durable history when the worker can't replay it; capture a full history to a local replay fixture. | shared: `--stack`, `--address`, `--namespace`; `history`: `-n/--limit <200>`, `-f/--follow`, `--no-compact`, `-p/--show-payloads` (decrypts via `TEMPORAL_ENCODING_KEY` from the K8s secret); `recover-conversation`: `--out <path>`, `--json`, `--snapshot` (structured `{conversationId,messages,artifacts,focus}` blob); `capture-history`: `--out <path>` (default `~/.mesh/replay-histories/<wfId>.json`, do not commit) | <!-- skill-lint-disable-next-line — row documents the mesh-owned kubectl wrappers; the backticked `aws eks get-token` describes what the CLI runs internally, not an operator step -->
 | `mesh kubectl` / `mesh logs` / `mesh exec` | `kubectl [args…]`, `logs [service\|deployment/x\|k=v]`, `exec <service> -- <cmd>` | Cluster access for a **deployed** app — debug CrashLoops/logs without broader creds. Assumes the app's `mesh:deployerRole`, builds a session kubeconfig from the platform `eks` SSM export (`aws eks get-token` — no `eks:DescribeCluster` / `~/.kube/config` needed), shells out to kubectl. Defaults the namespace to the app's own (deployer RBAC is tenant-namespace-scoped). **Use `--stack <name>` to target the deployed stack (e.g. `dev`, not `dev-local`).** | `--stack <name>`; `logs`: `-f/--follow`, `--tail <200>`, `-c/--container`, `--previous`; `exec`: `-c/--container` |
 
@@ -163,6 +167,7 @@ land in `apps/<name>/`:
 mesh create-app --tenant acme --name billing --primitives service,database,temporal
 cd apps/billing && pnpm install
 mesh skills sync             # picks up the platform skills now that deps are installed
+mesh app check apps/billing  # the Mesh app contract — create-app already ran it; re-run before every PR
 mesh stack init              # personal dev-{github-user} stack (deploy:false)
 mesh deploy up --yes         # pulumi up via mesh:deployerRole
 mesh dev                     # tunnels + secrets + tmux (needs VPN for VPC access)
@@ -303,6 +308,13 @@ MCP `agent_*` tools use; see the dedicated
 (registry format, auth model, the `conversation_unavailable` → `mesh temporal
 recover-conversation` break-glass path, and the MCP-vs-CLI relationship).
 
+### 7b. Workspace environments are driven from mesh-studio
+
+A Studio workspace's environment (live container, grace, build queue) is read and signalled
+by `studio workspace status|restart|reseed|rebuild` from mesh-studio's `@mesh-tech/studio-cli`,
+which builds on this package's `@mesh-tech/mesh-cli/temporal` (`connect`) and
+`@mesh-tech/mesh-cli/temporal-codec` exports. This CLI has no `workspace` command.
+
 ### 8. Relaunch safety — don't strand live conversations
 
 For a **code-only** change, prefer a scoped `mesh dev restart <service>` over a full
@@ -373,5 +385,5 @@ pulumi, vpn, and log helpers.
 
 ## See also
 
-- `@mesh-tech/app-kit#core` — app-kit bundles this CLI; consumers usually invoke it as `pnpm mesh <cmd>`
+- `@mesh-tech/app-kit#core` — app-kit's `mesh` bin is a shim onto this CLI, which is an **optional peer**: declare `@mesh-tech/mesh-cli` in your repo root's devDependencies. Consumers then invoke it as `pnpm mesh <cmd>`
 - `@mesh-tech/credentials#core` — credential resolution the auth/deploy flows build on

package/templates/api-auth/AGENTS.md.hbs

@@ -14,3 +14,9 @@
   provider when @mesh-tech/authz ships it.
 - Pattern skills for authn/authz ship inside those packages (TanStack
   Intent discovers them after `pnpm install`).
+- The app meets the Mesh app contract (`@mesh-tech/app-kit#apps` →
+  `references/app-contract.md`): access is surfaced through the Hub by the
+  `SpiceDBSchema` + `AppAuthzPointer` wiring in `index.ts`, and every service
+  logs through `@mesh-tech/logger`. `mesh app check` verifies it — run it
+  before opening a PR; never add a users table, an email allowlist, or a
+  manual Zitadel step instead.

package/templates/api-auth/README.md.hbs

@@ -47,21 +47,30 @@ is per-subject, in SpiceDB, exactly like the deployed platform.
 
 ## Deploy to a tenant environment
 
-The deployed Service runs behind the platform's oauth2-proxy sidecar
-(`auth: { provider: "mesh", … }` in `index.ts`), which needs its own OIDC
-client in the platform Zitadel:
-
 ```bash
 mesh login {{tenant}}.dev
-pulumi config set {{name}}:authClientId <clientId>
-pulumi config set --secret {{name}}:authClientSecret <clientSecret>
 mesh deploy up --yes
 ```
 
+A browser-facing Service you add later signs people in through the platform
+proxy (`auth: { provider: "mesh" }`). The proxy pins its sign-in callback to
+that Service's own ingress hostname; a Service that answers for more than one
+hostname (`ingress.extraHostnames`) sets `auth.deriveRedirectUrl: true` so each
+host gets its own callback, and registers a redirect URI per host at the IdP.
+
+`index.ts` owns the whole access surface, so there is nothing to create by
+hand: `ZitadelAppIdentity` makes the app's Zitadel project + roles,
+`SpiceDBSchema` compiles `api/src/schema.ts` into the app's own SpiceDB and
+publishes the ops-hub metadata, and `AppAuthzPointer` tells the Hub where to
+look. People, roles, API keys and sign-in activity are then administered from
+the Hub's **App → Access** tab — never by a runbook step. The contract behind
+that: `@mesh-tech/app-kit#apps` → `references/app-contract.md`; `mesh app
+check` verifies it.
+
 ## Layout
 
-- `index.ts` — Pulumi program (`Service` with platform auth + `/health` open)
+- `index.ts` — Pulumi program: Zitadel identity → SpiceDB + schema → `Service` → `AppAuthzPointer`
 - `api/src/index.ts` — Hono app: authn middleware + authz `require()`
 - `api/src/schema.ts` — the authorization schema (single source of truth)
 - `api/src/spicedb-http-provider.ts` — starter `AuthzProvider` (HTTP API)
-- `api/src/seed-authz.ts` — local schema write + grant
+- `api/scripts/seed-authz.ts` — local schema write + grant

package/templates/api-auth/api/package.json.hbs

@@ -8,11 +8,12 @@
     "start": "node dist/index.js",
     "build": "esm-bundle src/index.ts --outfile dist/index.js",
     "check-types": "tsc --noEmit",
-    "seed:authz": "tsx src/seed-authz.ts"
+    "seed:authz": "tsx scripts/seed-authz.ts"
   },
   "dependencies": {
     "@mesh-tech/authn": "latest",
     "@mesh-tech/authz": "latest",
+    "@mesh-tech/logger": "latest",
     "@opentelemetry/auto-instrumentations-node": "^0.78.0",
     "@mesh-tech/sinks": "latest",
     "hono": "^4.0.0",

package/templates/api-auth/api/{src → scripts}/seed-authz.ts.hbs

@@ -8,11 +8,11 @@
  */
 
 import { compileSpiceDBSchema } from "@mesh-tech/authz/compilers";
-import { schema } from "./schema.js";
-import { spiceDbHttpProvider } from "./spicedb-http-provider.js";
+import { schema } from "../src/schema.js";
+import { spiceDbHttpProvider } from "../src/spicedb-http-provider.js";
 
 const ENDPOINT = process.env.SPICEDB_HTTP_ENDPOINT ?? "http://localhost:8443";
-const KEY = process.env.SPICEDB_PRESHARED_KEY ?? "local-dev-key";
+const KEY = process.env.SPICEDB_TOKEN ?? process.env.SPICEDB_PRESHARED_KEY ?? "local-dev-key";
 
 // The Zitadel subject (`sub` claim) of the user to grant. Find it after
 // `mesh login local`: the CLI caches it in ~/.config/mesh/credentials.json,

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

@@ -10,7 +10,7 @@
  *   GET /api/report  permission-gated (needs report:view via SpiceDB → else 403)
  *
  * Environment (mesh dev injects all of these — local or tethered):
- *   PORT, ZITADEL_ISSUER, SPICEDB_ENDPOINT, SPICEDB_PRESHARED_KEY
+ *   PORT, ZITADEL_ISSUER, ZITADEL_PROJECT_ID, SPICEDB_HTTP_ENDPOINT, SPICEDB_TOKEN
  */
 
 import { Hono } from "hono";
@@ -20,22 +20,31 @@ import { zitadelJwtScheme } from "@mesh-tech/authn/schemes/zitadel-jwt";
 import { createAuthnMiddleware, type AuthnVariables } from "@mesh-tech/authn/hono";
 import { createAuthz } from "@mesh-tech/authz/runtime";
 import { createAuthzMiddleware, type AuthzVariables } from "@mesh-tech/authz/hono";
+import { createLogger, requestLogger } from "@mesh-tech/logger";
 import { schema } from "./schema.js";
 import { spiceDbHttpProvider } from "./spicedb-http-provider.js";
 
 const PORT = parseInt(process.env.PORT ?? "3000", 10);
 const ZITADEL_ISSUER = process.env.ZITADEL_ISSUER ?? "http://localhost:8080";
+// Every service logs through @mesh-tech/logger (the Mesh app contract, gate 0.4).
+const log = createLogger({ service: "{{name}}-api" });
 
 // --- authn: who is calling ---
 
 // Audience: locally, mesh dev injects the seeded CLI app's clientId
-// (tokens come from `mesh login local`); in the cloud this is the app's own
-// audience and consumers request its project-audience scope.
-const AUTH_AUDIENCE = process.env.AUTH_AUDIENCE ?? "{{name}}";
+// (tokens come from `mesh login local`); deployed, the app's OWN Zitadel
+// project id (ZitadelAppIdentity in index.ts) is the audience, and passing it
+// as `projectId` makes the scheme read the project-keyed roles claim.
+const ZITADEL_PROJECT_ID = process.env.ZITADEL_PROJECT_ID;
+const AUTH_AUDIENCE = process.env.AUTH_AUDIENCE ?? ZITADEL_PROJECT_ID ?? "{{name}}";
 
 const authn = createAuthn({
   schemes: {
-    "zitadel-jwt": zitadelJwtScheme({ issuer: ZITADEL_ISSUER, audience: AUTH_AUDIENCE }),
+    "zitadel-jwt": zitadelJwtScheme({
+      issuer: ZITADEL_ISSUER,
+      audience: AUTH_AUDIENCE,
+      ...(ZITADEL_PROJECT_ID ? { projectId: ZITADEL_PROJECT_ID } : {}),
+    }),
   },
 });
 const { middleware: requireAuth, public: publicRoute } = createAuthnMiddleware(authn);
@@ -49,13 +58,14 @@ const authz = createAuthz({
       provider: spiceDbHttpProvider({
         endpoint: process.env.SPICEDB_HTTP_ENDPOINT ?? "http://localhost:8443",
         // "local-dev-key" is the `mesh start` stack's key — local ONLY. In
-        // any deployed env the platform injects SPICEDB_PRESHARED_KEY; fail
-        // loudly rather than silently authing with the public default.
+        // any deployed env `spicedb.link()` (index.ts) injects SPICEDB_TOKEN;
+        // fail loudly rather than silently authing with the public default.
         presharedKey:
+          process.env.SPICEDB_TOKEN ??
           process.env.SPICEDB_PRESHARED_KEY ??
           (process.env.NODE_ENV === "production"
             ? (() => {
-                throw new Error("SPICEDB_PRESHARED_KEY is required in production");
+                throw new Error("SPICEDB_TOKEN is required in production");
               })()
             : "local-dev-key"),
       }),
@@ -73,6 +83,7 @@ const m = createAuthzMiddleware(authz, {
 // --- routes ---
 
 const app = new Hono<{ Variables: AuthnVariables & AuthzVariables }>();
+app.use("*", requestLogger(log));
 
 // Open: no token needed (also excluded from the oauth2-proxy in the cloud)
 app.get("/health", publicRoute(), (c) => c.json({ status: "ok" }));
@@ -92,5 +103,5 @@ app.get("/api/report", m.require("report", "view", { id: () => "quarterly" }), (
 );
 
 serve({ fetch: app.fetch, port: PORT }, () => {
-  console.log(`{{name}} api listening on :${PORT} (issuer: ${ZITADEL_ISSUER})`);
+  log.info({ port: PORT, issuer: ZITADEL_ISSUER }, "{{name}} api listening");
 });

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

@@ -1,54 +1,102 @@
 /**
- * {{titleCase name}} — Platform-authenticated API
+ * {{titleCase name}} — Platform-authenticated API (authz mode "policy-engine").
  *
- * Infrastructure: AppEnvironment + API Service behind platform auth
- * (oauth2-proxy sidecar against the platform Zitadel).
+ * authn: Zitadel JWTs verified in-process (@mesh-tech/authn) against the app's
+ * OWN Zitadel project. authz: schema-driven permission checks in the app's OWN
+ * SpiceDB (@mesh-tech/authz). Everything the Hub needs to administer people,
+ * roles and API keys for this app is published from here — nothing is created
+ * by hand in Zitadel and nothing lives in a runbook (the Mesh app contract,
+ * gate H: `@mesh-tech/app-kit#apps` → references/app-contract.md).
  *
- * Local:   mesh start && mesh dev   (runtime auth only — no proxy sidecar)
+ * Wires, IN ORDER:
+ *   1. ZitadelConnector   — authed provider for the platform Zitadel.
+ *   2. ZitadelAppIdentity — this app's OWN project; roles = schema.coarseRoles.
+ *   3. AppEnvironment     — namespace + providers, bound to the app's project.
+ *   4. SpiceDB            — the app's OWN SpiceDB instance (shared-DB mode).
+ *   5. SpiceDBSchema      — compiles api/src/schema.ts to .zed + ops-hub
+ *                           metadata, applies it, exports the metadata to SSM.
+ *   6. api Service        — Hono app: authn + authz middleware, linked to SpiceDB.
+ *   7. AppAuthzPointer    — LAST. Tells the Hub where this app's authz lives.
+ *
+ * Prerequisite: the target platform must have Zitadel enabled — ZitadelConnector
+ * eager-reads it at preview time.
+ *
+ * Local:   mesh start && mesh dev   (the local platform's Zitadel + SpiceDB)
  * Deploy:  mesh deploy up
  */
 
 import * as pulumi from "@pulumi/pulumi";
-import * as path from "node:path";
-import { fileURLToPath } from "node:url";
-import { mesh } from "@mesh-tech/app-kit";
+import { mesh } from "@mesh-tech/app-kit/infra";
+import { compileOpsHubMetadata, compileSpiceDBSchema } from "@mesh-tech/authz";
+// The authz schema is the single source of truth, shared by the api (enforces
+// it) and this Pulumi program (compiles it to SpiceDB + ops-hub metadata + roles).
+import { schema as schemaDef } from "./api/src/schema.js";
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const { tenant, platform, stack, deploy } = mesh.apps.getConfig(pulumi);
+const appName = "{{name}}";
+
+// --- 1. Connector — authed provider for the platform Zitadel. ---
+const connector = new mesh.auth.ZitadelConnector("idp", { tenant, env: platform.env });
 
-// --- Environment ---
+// --- 2. App identity — this app's OWN Zitadel project + roles. ---
+// The schema's coarse roles become Zitadel PROJECT ROLES: the vocabulary the
+// Hub grants people and API keys against. An `api`-type application is the
+// resource server tokens are minted for (its clientId is the JWT audience).
+const identity = new mesh.auth.ZitadelAppIdentity("identity", {
+  connector,
+  tenant,
+  env: platform.env,
+  project: { name: appName },
+  roles: [...schemaDef.coarseRoles],
+  applications: {
+    api: { type: "api" },
+  },
+});
 
+// --- 3. Environment — bound to the app's own project via zitadelAppProjectId. ---
 const env = new mesh.apps.AppEnvironment("env", {
   tenant,
   platform,
   stack,
   deploy,
-  appName: "{{name}}",
+  appName,
   namespace: true,
-  rootDir: __dirname,
+  database: false,
+  zitadelAppProjectId: identity.projectId,
 });
 
-// --- Services ---
+// --- 4. SpiceDB — the app's OWN instance (omit `rds` → the platform's shared RDS). ---
+// `httpEnabled` serves the REST gateway the starter spicedb-http-provider talks to.
+const spicedb = new mesh.auth.SpiceDB("spicedb", { env, httpEnabled: true });
 
-// The oauth2-proxy sidecar needs its own OIDC client in the platform
-// Zitadel. Approved tenant-auth pattern: one Zitadel PROJECT per app (in
-// your app tenant's org), one APPLICATION per service — create the app's
-// project if it doesn't exist, add a web application for this service, and
-// set both values on the stack:
-//   pulumi config set {{name}}:authClientId <clientId>
-//   pulumi config set --secret {{name}}:authClientSecret <clientSecret>
-const appConfig = new pulumi.Config("{{name}}");
+// --- 5. Schema — compile, apply, and publish the ops-hub metadata. ---
+// `opsHubMetadataRef` is the SSM path the pointer below hands to the Hub; without
+// it the Hub's create-key and role catalog answer 409 METADATA_UNPUBLISHED.
+const schema = new mesh.auth.SpiceDBSchema("schema", {
+  env,
+  spicedb,
+  compiled: {
+    zed: compileSpiceDBSchema(schemaDef).zed,
+    metadata: compileOpsHubMetadata(schemaDef),
+  },
+});
 
+// --- 6. api Service — in-process authn + authz; SpiceDB reached via link(). ---
 const api = new mesh.apps.Service("api", {
   env,
+  title: "{{titleCase name}} API",
+  description: "Platform-authenticated API for {{titleCase name}}",
   runtime: "node",
   src: "./api",
   port: 3000,
-  auth: {
-    provider: "mesh", // issuer auto-derived from the platform Zitadel
-    clientId: appConfig.require("authClientId"),
-    clientSecret: appConfig.requireSecret("authClientSecret"),
-    allowUnauthenticated: ["/health"],
+  // spicedb.link() injects SPICEDB_ENDPOINT (gRPC) + SPICEDB_TOKEN and the IAM
+  // to reach the instance; the HTTP gateway address rides alongside for the
+  // starter provider.
+  link: [spicedb.link()],
+  environment: {
+    ZITADEL_ISSUER: pulumi.output(env.zitadel).apply((z) => z?.issuer ?? ""),
+    ZITADEL_PROJECT_ID: identity.projectId,
+    SPICEDB_HTTP_ENDPOINT: spicedb.httpEndpoint,
   },
   ingress: env.buildIngress({
     subdomain: "{{name}}-api",
@@ -58,8 +106,14 @@ const api = new mesh.apps.Service("api", {
   resources: { cpu: "100m", memory: "128Mi" },
 });
 
+// --- 7. AppAuthzPointer — LAST. The Hub's App → Access tab reads this. ---
+new mesh.auth.AppAuthzPointer("authz", { env, mode: "policy-engine", opsHubMetadataRef: schema.opsHubMetadataRef });
+
 // --- Outputs ---
 
 export const app = env.register({
   description: "{{titleCase name}} — platform-authenticated API (authn + authz)",
 });
+
+/** The app's own Zitadel project id (grant people and API keys against this). */
+export const zitadelProjectId = identity.projectId;

package/templates/api-auth/package.json.hbs

@@ -11,6 +11,8 @@
   },
   "dependencies": {
     "@mesh-tech/app-kit": "latest",
+    "@mesh-tech/authz": "latest",
+    "@mesh-tech/infra-components": "latest",
     "@pulumi/pulumi": "^3.214.1"
   },
   "devDependencies": {

package/templates/api-role-gating/api/package.json.hbs

@@ -16,6 +16,7 @@
   "dependencies": {
     "@mesh-tech/authn": "latest",
     "@mesh-tech/authz": "latest",
+    "@mesh-tech/logger": "latest",
     "hono": "^4.0.0",
     "@hono/node-server": "^1.0.0"
   },

package/templates/api-role-gating/api/src/main.ts.hbs

@@ -10,17 +10,22 @@ import { serve } from "@hono/node-server";
 import { Hono } from "hono";
 import { createAuthnMiddleware, type AuthnVariables } from "@mesh-tech/authn/hono";
 import { createAuthzMiddleware, type AuthzVariables } from "@mesh-tech/authz/hono";
+import { createLogger, requestLogger } from "@mesh-tech/logger";
 import { createAuthnFromEnv } from "./authn.js";
 import { createAppAuthz } from "./authz.js";
 
 type TestAuth = { subjectSub: string; coarseRole?: string | readonly string[] };
 type AppEnv = { Variables: AuthnVariables & AuthzVariables };
 
+// Every service logs through @mesh-tech/logger (the Mesh app contract, gate 0.4).
+const log = createLogger({ service: "{{name}}-api" });
+
 /** The role-gated route paths (kept in one place so authn + authz agree). */
 const GATED = ["/admin", "/reports"] as const;
 
 export const createApp = (deps: { testAuth?: TestAuth } = {}) => {
   const app = new Hono<AppEnv>();
+  app.use("*", requestLogger(log));
   const m = createAuthzMiddleware(createAppAuthz());
 
   // Open: no token needed.
@@ -54,5 +59,5 @@ export const createApp = (deps: { testAuth?: TestAuth } = {}) => {
 if (process.env.NODE_ENV !== "test" && process.argv[1]?.endsWith("main.js")) {
   const port = Number(process.env.PORT ?? 3000);
   serve({ fetch: createApp().fetch, port });
-  console.log(`{{name}} api listening on :${port} (role-gating)`);
+  log.info({ port, mode: "role-gating" }, "{{name}} api listening");
 }

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

@@ -24,7 +24,7 @@
  * Deploy: mesh deploy up
  */
 import * as pulumi from "@pulumi/pulumi";
-import { mesh } from "@mesh-tech/app-kit";
+import { mesh } from "@mesh-tech/app-kit/infra";
 import { compileOpsHubMetadata } from "@mesh-tech/authz";
 import type { OpsHubMetadata } from "@mesh-tech/authz";
 // The authz schema is the single source of truth, shared by the api (enforces

package/templates/api-role-gating/package.json.hbs

@@ -11,6 +11,7 @@
   },
   "dependencies": {
     "@mesh-tech/app-kit": "latest",
+    "@mesh-tech/infra-components": "latest",
     "@mesh-tech/authz": "latest",
     "@pulumi/pulumi": "^3.214.1"
   },

package/templates/external-service/api/package.json.hbs

@@ -11,8 +11,10 @@
   },
   "dependencies": {
     "@mesh-tech/app-kit": "latest",
+    "@mesh-tech/secrets": "latest",
     "@opentelemetry/auto-instrumentations-node": "^0.78.0",
     "@mesh-tech/http-client": "latest",
+    "@mesh-tech/logger": "latest",
     "hono": "^4.0.0",
     "@hono/node-server": "^1.0.0"
   },

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

@@ -19,6 +19,7 @@ import { Hono } from "hono";
 import { resolveCredentials } from "@mesh-tech/app-kit/credentials";
 import { traceExternalCall } from "@mesh-tech/app-kit/tracing";
 import { enhanceFetch } from "@mesh-tech/http-client";
+import { createLogger, requestLogger } from "@mesh-tech/logger";
 
 interface VendorpayCredentials extends Record<string, string> {
   baseUrl: string;
@@ -27,7 +28,11 @@ interface VendorpayCredentials extends Record<string, string> {
 
 const vendorFetch = enhanceFetch();
 
+// Every service logs through @mesh-tech/logger (the Mesh app contract, gate
+// 0.4): structured, masked, trace-correlated lines the Hub can search.
+const log = createLogger({ service: "{{name}}-api" });
 const app = new Hono();
+app.use("*", requestLogger(log));
 
 app.get("/health", (c) => c.json({ status: "ok" }));
 
@@ -62,7 +67,7 @@ app.post("/payments/quote", async (c) => {
   // Log vendor interactions with the service name — these lines are what
   // the Hub's Integrations → Monitoring → Logs view surfaces (it searches
   // consumer logs for mentions of the external service).
-  console.log(`[vendorpay] quote requested amount=${amount} → ${response.status}`);
+  log.info({ externalService: "vendorpay", amount, status: response.status }, "vendorpay quote requested");
 
   if (!response.ok) {
     return c.json(
@@ -77,5 +82,5 @@ app.post("/payments/quote", async (c) => {
 
 const port = Number(process.env.PORT ?? 3000);
 serve({ fetch: app.fetch, port }, () => {
-  console.log(`[API] {{titleCase name}} API listening on port ${port}`);
+  log.info({ port }, "{{titleCase name}} API listening");
 });

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

@@ -16,7 +16,7 @@
 import * as pulumi from "@pulumi/pulumi";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-import { mesh } from "@mesh-tech/app-kit";
+import { mesh } from "@mesh-tech/app-kit/infra";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const { tenant, platform, stack, deploy } = mesh.apps.getConfig(pulumi);