@mesh-tech/mesh-cli 0.32.0 → 0.34.0

package/fragments/base/index.ts.hbs

@@ -8,6 +8,12 @@ import * as pulumi from "@pulumi/pulumi";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { mesh } from "@mesh-tech/app-kit/infra";
+{{#if events}}
+import { compileOpsHubMetadata } from "@mesh-tech/authz";
+// The authz schema is the single source of truth, shared by the api (enforces
+// it) and this program (compiles it to ops-hub metadata + Zitadel roles).
+import schemaDef from "./schema.js";
+{{/if}}
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const { tenant, platform, stack, deploy } = mesh.apps.getConfig(pulumi);
@@ -16,6 +22,32 @@ const { tenant, platform, stack, deploy } = mesh.apps.getConfig(pulumi);
 const TASK_QUEUE = "{{name}}";
 {{/if}}
 
+{{#if events}}
+// =============================================================================
+// Identity — this app's OWN Zitadel project, BEFORE the environment
+// =============================================================================
+//
+// The events service authorizes bearer callers by this project's roles claim,
+// so the two events roles are project roles here. They are spread rather than
+// written out: `mesh.apps.EVENTS_PROJECT_ROLES` is the vocabulary the service
+// itself reads, and a hand-copied spelling that drifts is a partner refused
+// with no explanation. The primitive cannot add them for you — this identity
+// builds its roles now, before the events service exists.
+
+const connector = new mesh.auth.ZitadelConnector("idp", { tenant, env: platform.env });
+
+const identity = new mesh.auth.ZitadelAppIdentity("identity", {
+  connector,
+  tenant,
+  env: platform.env,
+  project: { name: "{{name}}" },
+  roles: [...schemaDef.coarseRoles, ...mesh.apps.EVENTS_PROJECT_ROLES],
+  applications: {
+    api: { type: "api" },
+  },
+});
+
+{{/if}}
 // =============================================================================
 // Environment
 // =============================================================================
@@ -28,6 +60,17 @@ const env = new mesh.apps.AppEnvironment("env", {
   appName: "{{name}}",
   namespace: true,
   rootDir: __dirname,
+{{#if events}}
+  // Bind the env to the app's OWN project. Without it env.zitadel silently
+  // falls back to the shared platform project, whose roles are not this app's.
+  zitadelAppProjectId: identity.projectId,
+  // The events service's delivery worker is one Temporal workflow per event.
+  temporal: {
+    codecServer: {
+      ingressSubdomain: "codec-{{name}}",
+    },
+  },
+{{else}}
 {{#if temporal}}
   temporal: {
     codecServer: {
@@ -35,6 +78,7 @@ const env = new mesh.apps.AppEnvironment("env", {
     },
   },
 {{/if}}
+{{/if}}
 });
 
 // =============================================================================
@@ -51,6 +95,41 @@ const uploads = new mesh.apps.Bucket("uploads", {
   forceDestroy: stack !== "prod",
 });
 {{/if}}
+{{#if events}}
+
+// The knobs an operator tunes from the Hub's Config tab. The events service's
+// own tunables are spread in rather than declared here, and the primitive
+// deliberately creates no config of its own: app config values are singular
+// per app — one value store, one synced Secret, one published schema — so a
+// second component declaring them would collide with this one.
+const config = new mesh.apps.AppConfig("config", {
+  env,
+  fields: {
+    ...mesh.apps.eventsConfigFields(),
+  },
+});
+
+// Events and webhooks: the service, its own database, an app-scoped KMS key
+// for endpoint credentials, the publisher key, the Zitadel introspection app,
+// the delivery task queue and the registry surface — all children of this one
+// declaration.
+//
+// A knob written HERE is pinned in code: Kubernetes keeps an explicit `env`
+// entry over the `envFrom` the app values arrive through, so a value in this
+// block wins over whatever an operator saves in the Hub. Leave one out to hand
+// it over; an app value nobody has set arrives empty and the service reads
+// that as "use the default".
+const events = new mesh.apps.EventsService("events", {
+  env,
+  identity: { connector, projectId: identity.projectId },
+  config,
+  // "thin" sends identifiers only, so nothing the API would mask reaches a
+  // third-party endpoint and the consumer follows the identifiers back to the
+  // API, where field policy applies as on any read. Switch to "full" only for
+  // an app whose events carry no policy-governed fields.
+  payload: "thin",
+});
+{{/if}}
 
 // =============================================================================
 // Services
@@ -76,6 +155,11 @@ const api = new mesh.apps.Service("api", {
 {{/if}}
 {{#if temporal}}
     env.temporal!.link({ environmentPrefix: "TEMPORAL", taskQueue: TASK_QUEUE }),
+{{/if}}
+{{#if events}}
+    // EVENTS_SERVICE_URL + EVENTS_API_KEY — the only two values that cross
+    // between this process and the events service.
+    events.link(),
 {{/if}}
   ],
   ingress: env.buildIngress({ subdomain: "{{name}}" }),
@@ -151,6 +235,20 @@ new mesh.apps.ApiDocs("docs", {
 // Outputs
 // =============================================================================
 
+{{#if events}}
+// =============================================================================
+// Access — LAST. The pointer is what the Hub's App -> Access tab reads; without
+// it the tab is blank and no one can be granted a role, including the two the
+// events service authorizes its subscribers by.
+// =============================================================================
+
+new mesh.auth.AppAuthzPointer("authz", {
+  env,
+  mode: "role-gating",
+  opsHubMetadata: compileOpsHubMetadata(schemaDef),
+});
+
+{{/if}}
 export const app = env.register({
   // 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
@@ -175,3 +273,9 @@ export const apiUrl = api.url;
 {{#if temporal}}
 export const workerTaskQueue = worker.taskQueue;
 {{/if}}
+{{#if events}}
+/** The events service's base URL — where subscribers register and publishers post. */
+export const eventsUrl = events.url;
+/** This app's own Zitadel project id — grant events:subscriber against it. */
+export const zitadelProjectId = identity.projectId;
+{{/if}}

package/fragments/base/package.json.hbs

@@ -9,13 +9,23 @@
   },
   "dependencies": {
     "@mesh-tech/app-kit": "{{#if workspaceDeps}}workspace:*{{else}}{{meshRange}}{{/if}}",
+{{#if events}}
+    "@mesh-tech/authz": "{{#if workspaceDeps}}workspace:*{{else}}{{authzRange}}{{/if}}",
+    "@mesh-tech/events-service": "{{#if workspaceDeps}}workspace:*{{else}}{{eventsServiceRange}}{{/if}}",
+{{/if}}
     "@mesh-tech/infra-components": "{{#if workspaceDeps}}workspace:*{{else}}{{meshRange}}{{/if}}",
+{{#if events}}
+    "@temporalio/worker": "^1.17.0",
+{{/if}}
     "@pulumi/aws": "6.66.2",
     "@pulumi/kubernetes": "4.24.1",
     "@pulumi/pulumi": "3.214.1"
   },
   "devDependencies": {
     "@types/node": "{{#if workspaceDeps}}catalog:{{else}}{{typesNodeRange}}{{/if}}",
+{{#if events}}
+    "esbuild": "^0.25.8",
+{{/if}}
     "tsx": "{{#if workspaceDeps}}catalog:{{else}}{{tsxRange}}{{/if}}",
     "typescript": "{{#if workspaceDeps}}catalog:{{else}}{{typescriptRange}}{{/if}}"
   }

package/fragments/events/api/src/events.ts.hbs

@@ -0,0 +1,161 @@
+/**
+ * The publisher side of {{titleCase name}}'s events.
+ *
+ * Two environment variables reach this process through the events service's
+ * `link()` — `EVENTS_SERVICE_URL` and `EVENTS_API_KEY` — and nothing else
+ * crosses between the app and the events service.
+ *
+ * Publishing is **fail-open and fire-and-forget**: a publish never fails the
+ * operation that emitted the event, and a process whose environment is not
+ * wired gets a client that resolves every call to nothing. That is the design,
+ * not a shortcut — making it strict would couple every request this app serves
+ * to the events service being up. The guarantee it buys is stated plainly:
+ * before the service accepts an event, delivery is at-most-once; after it, the
+ * workflow id dedupes and the retry ladder guarantees attempts.
+ *
+ * @example
+ * // in a handler, AFTER the write commits
+ * void publish("{{name}}.thing.created", { thing_id: id }, `{{name}}:${requestId}`);
+ */
+
+import { createLogger } from "@mesh-tech/logger";
+
+const log = createLogger({ service: "{{name}}-api" });
+
+const SERVICE_URL = process.env.EVENTS_SERVICE_URL;
+const API_KEY = process.env.EVENTS_API_KEY;
+
+if (!SERVICE_URL || !API_KEY) {
+  log.warn(
+    "EVENTS_SERVICE_URL or EVENTS_API_KEY is unset — publishes are no-ops in this process",
+  );
+}
+
+/**
+ * The wait before each successive registration attempt, in milliseconds.
+ *
+ * Registration is idempotent and additive, so it retries forever rather than
+ * giving up — the design's contract is that a service can boot before its
+ * events service is reachable. The ladder is bounded and then capped, so a
+ * long outage settles at one attempt every five minutes instead of hammering.
+ */
+const REGISTER_BACKOFF_MS = [1_000, 2_000, 4_000, 8_000, 16_000, 30_000, 60_000, 300_000];
+
+/**
+ * How long to wait after `attemptsMade` failed attempts.
+ *
+ * The index trails the attempt COUNT by one, deliberately: after the first
+ * attempt fails the wait is the FIRST rung. They are two different counters,
+ * and handing one across as the other is what makes a ladder's first rung
+ * unreachable while every document describing it still reads correctly.
+ *
+ * @example
+ * registerBackoffMs(1); // => 1000 — the first rung, after the first failure
+ * registerBackoffMs(2); // => 2000
+ * registerBackoffMs(99); // => 300000 — saturated at the cap
+ */
+export function registerBackoffMs(attemptsMade: number): number {
+  const index = Math.min(Math.max(attemptsMade - 1, 0), REGISTER_BACKOFF_MS.length - 1);
+  return REGISTER_BACKOFF_MS[index]!;
+}
+
+const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+/** The event catalog this service publishes. Names are `{service}.{resource}.{action}`. */
+export const EVENT_TYPES = {
+  thingCreated: "{{name}}.thing.created",
+} as const;
+
+/**
+ * Register this service's catalog with the events service. Additive and
+ * first-registrar-wins: removing a type here never deletes the row, and
+ * subscribers keep working across a deploy. Call it once at boot.
+ *
+ * **This never rejects.** A transient failure — the events pod still starting,
+ * a connection refused, a DNS miss — retries in the background on
+ * {@link registerBackoffMs} forever, because registration is idempotent. That
+ * is not politeness: the caller is `void registerEvents()` at module scope, so
+ * a rejection would be unhandled, and Node turns an unhandled rejection into
+ * an uncaught exception and exits — this API's pod would CrashLoopBackOff on a
+ * condition in a sibling service.
+ */
+export async function registerEvents(): Promise<void> {
+  if (!SERVICE_URL || !API_KEY) return;
+  for (let attemptsMade = 1; ; attemptsMade++) {
+    try {
+      await attemptRegister();
+      if (attemptsMade > 1) log.info({ attemptsMade }, "event catalog registered");
+      return;
+    } catch (error) {
+      const waitMs = registerBackoffMs(attemptsMade);
+      // Escalate as the ladder REACHES its cap, not one attempt after it:
+      // by here the wait is already the longest this will ever be, and that
+      // is the moment an operator wants to hear about.
+      const saturated = attemptsMade >= REGISTER_BACKOFF_MS.length;
+      const line = { err: error, attemptsMade, retryInMs: waitMs };
+      if (saturated) log.error(line, "event catalog registration still failing");
+      else log.warn(line, "event catalog registration failed, retrying");
+      await sleep(waitMs);
+    }
+  }
+}
+
+/** One registration attempt. Throws; {@link registerEvents} owns the retrying. */
+async function attemptRegister(): Promise<void> {
+  await post("/events/registry/register", {
+    service: "{{name}}",
+    events: [
+      {
+        name: EVENT_TYPES.thingCreated,
+        description: "A thing reached a terminal created state",
+        payload_schema: {
+          type: "object",
+          properties: { thing_id: { type: "string" } },
+          required: ["thing_id"],
+          // Identifiers the thin envelope carries when a delivery has no body.
+          // The keys must be snake_case: they become keys in a snake_case
+          // envelope, and registration refuses anything else.
+          "x-mesh-resource": { type: "thing", id: "thing_id" },
+        },
+      },
+    ],
+  });
+}
+
+/**
+ * Publish one event, after the write it describes has committed.
+ *
+ * `idempotencyKey` is what makes a retry safe: the service persists one event
+ * row and starts one delivery workflow per key, and a replay answers 409,
+ * which is success.
+ */
+export async function publish(
+  eventType: string,
+  payload: Record<string, unknown>,
+  idempotencyKey: string,
+): Promise<void> {
+  if (!SERVICE_URL || !API_KEY) return;
+  try {
+    await post("/events/publish", {
+      event_type: eventType,
+      source_service: "{{name}}",
+      payload,
+      idempotency_key: idempotencyKey,
+    });
+  } catch (error) {
+    // A publish never fails the operation it describes.
+    log.warn({ err: error, eventType }, "publish failed");
+  }
+}
+
+async function post(path: string, body: unknown): Promise<void> {
+  const response = await fetch(`${SERVICE_URL}${path}`, {
+    method: "POST",
+    headers: { "content-type": "application/json", "x-api-key": API_KEY! },
+    body: JSON.stringify(body),
+  });
+  // A replay of an already-accepted event is a 409 and is success.
+  if (!response.ok && response.status !== 409) {
+    throw new Error(`${path} answered ${response.status}`);
+  }
+}

package/fragments/events/schema.ts.hbs

@@ -0,0 +1,23 @@
+/**
+ * Authorization schema — the single source of truth (@mesh-tech/authz).
+ *
+ * mode "role-gating": enforcement is a coarse-role check on the caller's
+ * Zitadel project roles. `coarseRoles` is the whole vocabulary — it becomes
+ * this app's Zitadel PROJECT ROLES (declared in `index.ts`), what the Hub's
+ * Access tab grants, and what the create-key wizard lists.
+ *
+ * The events service's own two roles are NOT listed here. They are the
+ * platform's vocabulary, not this app's, so `index.ts` spreads
+ * `mesh.apps.EVENTS_PROJECT_ROLES` alongside these — the roles end up in the
+ * same project either way, and keeping them out of the schema means the app's
+ * own enforcement never has to reason about them.
+ */
+
+import { defineSchema } from "@mesh-tech/authz/schema";
+
+export default defineSchema({
+  namespace: "{{name}}",
+  version: "0.1.0",
+  mode: "role-gating",
+  coarseRoles: ["admin", "viewer"] as const,
+});

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

@@ -11,6 +11,9 @@
 {{/if}}
 {{#if bucket}}
  * - UPLOADS_BUCKET, UPLOADS_REGION
+{{/if}}
+{{#if events}}
+ * - EVENTS_SERVICE_URL, EVENTS_API_KEY
 {{/if}}
  */
 
@@ -20,6 +23,9 @@ import { createLogger, requestLogger } from "@mesh-tech/logger";
 {{#if temporal}}
 import { createTemporalClient } from "@mesh-tech/app-kit/temporal-client";
 {{/if}}
+{{#if events}}
+import { EVENT_TYPES, publish, registerEvents } from "./events.js";
+{{/if}}
 
 const PORT = parseInt(process.env.PORT ?? "3000", 10);
 // Every service logs through @mesh-tech/logger (the Mesh app contract, gate
@@ -31,6 +37,15 @@ app.use("*", requestLogger(log));
 {{#if temporal}}
 const { withClient } = await createTemporalClient();
 {{/if}}
+{{#if events}}
+// Register this service's catalog at boot. Fire-and-forget by design: the
+// call is idempotent and additive, and a boot that waited on the events
+// service would couple this process's startup to it. `registerEvents` retries
+// in the background and never rejects; the `.catch` is the belt to that
+// braces — an unhandled rejection here would exit the process and turn a
+// sibling service's outage into this one's CrashLoopBackOff.
+void registerEvents().catch((err) => log.error({ err }, "event registration gave up"));
+{{/if}}
 
 // Health check
 app.get("/health", (c) => c.json({ status: "ok" }));
@@ -54,6 +69,18 @@ app.post("/workflow", async (c) => {
 });
 {{/if}}
 
+{{#if events}}
+// Publish AFTER the write commits — never before, and never in its
+// transaction. The idempotency key is what makes a retry of this handler
+// produce one event and one delivery run.
+app.post("/things", async (c) => {
+  const body = await c.req.json<{ id: string }>();
+  // ...create the thing here...
+  void publish(EVENT_TYPES.thingCreated, { thing_id: body.id }, `{{name}}:${body.id}`);
+  return c.json({ id: body.id }, 201);
+});
+
+{{/if}}
 // Start server
 serve({ fetch: app.fetch, port: PORT, hostname: "0.0.0.0" }, (info) => {
   log.info({ port: info.port }, "{{titleCase name}} API listening");

package/package.json

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

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

@@ -61,7 +61,12 @@ 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
+publishes the ops-hub metadata — `mesh deploy up` blocks on that Job and fails
+when it fails, so a green deploy means the schema is live. On a cold first
+deploy the Job can lose the race to SpiceDB's own startup and gives up on
+`backoffLimit`, well inside `timeoutMinutes`; `awaitCompletion: false` is the
+lever for that, not a larger `timeoutMinutes`, which does not extend the
+retries. `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

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

@@ -72,6 +72,13 @@ const spicedb = new mesh.auth.SpiceDB("spicedb", { env, httpEnabled: true });
 // --- 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.
+// `mesh deploy up` blocks on the schema-write Job and fails when it fails —
+// every permission check this API makes reads what that Job wrote, so a write
+// that never landed is not a deploy that succeeded. On a cold first deploy the
+// Job can lose the race to SpiceDB's own startup: it retries on backoffLimit
+// and gives up well inside timeoutMinutes, never running for the full budget.
+// If that is your estate, set `awaitCompletion: false` here rather than
+// raising `timeoutMinutes`, which does not extend the retries.
 const schema = new mesh.auth.SpiceDBSchema("schema", {
   env,
   spicedb,