@k2b/cloud 0.42.0 → 0.44.0

package/src/cli/apps.ts

@@ -1,4 +1,5 @@
-import { type CloudCliContext, command, defineCliCommands, flag } from "./index";
+import { AppDetailsSchema } from "../contracts/app-details";
+import { arg, type CloudCliContext, command, defineCliCommands, flag, localizeCloudCliText, printRows, printStructured } from "./index";
 
 type VisibleApp = {
   id: string;
@@ -13,28 +14,90 @@ const listApps = async (ctx: CloudCliContext, search: string | undefined) => {
   return ctx.readJson<{ items: VisibleApp[] }>(await ctx.fetch(`/api/apps${query}`));
 };
 
-export default defineCliCommands({
-  name: "apps",
-  summary: "List Cloud apps available to the current user.",
-  commands: [
-    command("list", {
-      summary: "List available Cloud apps",
-      flags: {
-        search: flag.string({ aliases: ["q"], description: "Filter by app name, id, or description" }),
-      },
-      run: async ({ ctx, flags }) => {
-        const result = await listApps(ctx, flags.search);
-        if (ctx.options.output === "json") {
-          ctx.json(result);
-          return;
-        }
-        ctx.table(result.items, [
-          { key: "id", label: "ID" },
-          { key: "name", label: "NAME" },
-          { key: "description", label: "DESCRIPTION" },
-          { key: "href", label: "URL" },
-        ]);
-      },
-    }),
-  ],
-});
+const build = (locale?: string) => {
+  const t = (en: string, de: string) => localizeCloudCliText(locale, { en, de });
+  return defineCliCommands({
+    name: "apps",
+    summary: t("List Cloud apps and inspect their declarations.", "Cloud-Apps auflisten und ihre Deklarationen prüfen."),
+    commands: [
+      command("show", {
+        summary: t(
+          "Inspect one app's access, events and notifications (admin)",
+          "Zugriff, Events und Benachrichtigungen einer App prüfen (Admin)",
+        ),
+        args: { app: arg.required({ description: t("App ID", "App-ID") }) },
+        run: async ({ ctx, args }) => {
+          const result = AppDetailsSchema.parse(
+            await ctx.readJson(await ctx.fetch(`/api/app-events/apps/${encodeURIComponent(args.app)}`)),
+          );
+          if (printStructured(ctx, result)) return;
+          const { app, access } = result;
+          const printOmitted = (shown: number, total: number) => {
+            if (total > shown) ctx.print(t(`… ${total - shown} more omitted`, `… ${total - shown} weitere ausgelassen`));
+          };
+          ctx.print(
+            `${t("App", "Anwendung")}: ${app.name} (${app.id}) · ${app.online ? t("online", "erreichbar") : t("offline", "nicht erreichbar")}`,
+          );
+          if (app.description) ctx.print(app.description);
+          ctx.print(`\n${t("Access", "Zugriff")}: ${access.kind ?? t("unknown (offline)", "unbekannt (offline)")}`);
+          if (access.roles.length) ctx.print(`${t("Roles", "Rollen")}: ${access.roles.join(", ")}`);
+          if (access.grantCount !== null) ctx.print(`${t("Grants", "Freigaben")}: ${access.grantCount}`);
+          ctx.print(`${t("Platform permissions", "Plattformrechte")}: ${access.platformPermissions.join(", ") || "—"}`);
+          ctx.print(`\n${t("Sends", "Sendet")} (${result.sends.length}/${result.totals.sends})`);
+          for (const event of result.sends) {
+            ctx.print(`${event.type} v${event.version} · ${event.title} · ${event.subscriberCount} ${t("subscribers", "Abonnenten")}`);
+            ctx.print(
+              `  ${event.subject}${event.place ? ` @ ${event.place}` : ""} · ${t("automation", "Automatisierung")}=${event.automation ? t("yes", "ja") : t("no", "nein")}`,
+            );
+          }
+          printOmitted(result.sends.length, result.totals.sends);
+          ctx.print(`\n${t("Hears", "Hört")} (${result.hears.length}/${result.totals.hears})`);
+          for (const subscription of result.hears) {
+            ctx.print(
+              `${subscription.eventType} v${subscription.version} · ${subscription.state}${subscription.isNew ? ` · ${t("new", "neu")}` : ""} · ${subscription.counts.failed} ${t("failed", "fehlgeschlagen")}`,
+            );
+            ctx.print(`  ${subscription.subscriptionId}${subscription.reason ? ` · ${subscription.reason}` : ""}`);
+            for (const failure of subscription.failedDeliveries)
+              ctx.print(
+                `  ${failure.id} · ${failure.code ?? t("failed", "fehlgeschlagen")} · ${failure.attempts} ${t("attempts", "Versuche")}`,
+              );
+          }
+          printOmitted(result.hears.length, result.totals.hears);
+          ctx.print(`\n${t("Notifications", "Benachrichtigungen")} (${result.notifications.length}/${result.totals.notifications})`);
+          for (const notification of result.notifications) {
+            ctx.print(`${notification.id} · ${notification.label} · ${notification.recipientKind}`);
+            ctx.print(
+              `  ${t("Required", "Erforderlich")}: ${notification.requiredChannels.join(", ") || "—"}; ${t("recommended", "empfohlen")}: ${notification.recommendedChannels.join(", ") || "—"}; ${t("excluded", "ausgeschlossen")}: ${notification.excludedChannels.join(", ") || "—"}`,
+            );
+          }
+          printOmitted(result.notifications.length, result.totals.notifications);
+        },
+      }),
+      command("list", {
+        summary: t("List available Cloud apps", "Verfügbare Cloud-Apps auflisten"),
+        flags: {
+          search: flag.string({
+            aliases: ["q"],
+            description: t("Filter by app name, id, or description", "Nach App-Name, ID oder Beschreibung filtern"),
+          }),
+        },
+        run: async ({ ctx, flags }) => {
+          const result = await listApps(ctx, flags.search);
+          printRows(ctx, result, result.items, [
+            { key: "id", label: "ID" },
+            { key: "name", label: "NAME" },
+            { key: "description", label: t("DESCRIPTION", "BESCHREIBUNG") },
+            { key: "href", label: "URL" },
+          ]);
+        },
+      }),
+    ],
+  });
+};
+
+const appsCliModule = build();
+export default {
+  ...appsCliModule,
+  help: (locale?: string) => build(locale).help?.(locale) ?? "",
+  run: (ctx: CloudCliContext) => build(ctx.options.locale).run(ctx),
+};

package/src/cli/avatar.ts

@@ -0,0 +1,64 @@
+import { readFile } from "node:fs/promises";
+import { type AvatarConfig, PersonAvatarSchema, RobotAvatarSchema } from "../contracts/avatar";
+import { MAX_AVATAR_BYTES } from "../contracts/profile";
+
+/** What `GET …/avatar` answers for a person or a service account. */
+export type CliAvatarState = {
+  kind: "photo" | "built" | "initials";
+  built: AvatarConfig | null;
+  hasPhoto: boolean;
+  photo: string | null;
+  avatarHash: string | null;
+};
+
+/** One row per fact: which picture shows, whether a photo is stored, then every part of the built avatar. */
+export const avatarRows = (state: CliAvatarState): Array<{ key: string; value: string }> => [
+  { key: "shows", value: state.kind === "built" ? (state.built?.kind === "robot" ? "robot" : "avatar") : state.kind },
+  { key: "photo", value: state.hasPhoto ? "stored" : "none" },
+  ...Object.entries(state.built ?? {})
+    .filter(([key]) => key !== "v" && key !== "kind")
+    .map(([key, value]) => ({ key, value: String(value) })),
+];
+
+/**
+ * Applies `part=value` pairs to a built avatar and validates the result against its shape set. An unknown part or
+ * value names what is allowed, so a person or an agent can correct the call without guessing.
+ */
+export const applyAvatarParts = <T extends AvatarConfig>(base: T, parts: readonly string[]): T => {
+  if (parts.length === 0) throw new Error("Pass at least one part=value, for example hair=curly.");
+  const schema = base.kind === "person" ? PersonAvatarSchema : RobotAvatarSchema;
+  const next: Record<string, unknown> = { ...base };
+  for (const part of parts) {
+    const [key, value, ...rest] = part.split("=");
+    if (!key || value === undefined || rest.length > 0) throw new Error(`Expected part=value, got "${part}".`);
+    const field = schema.shape[key as keyof typeof schema.shape];
+    if (!field || key === "v" || key === "kind") {
+      const known = Object.keys(schema.shape).filter((name) => name !== "v" && name !== "kind");
+      throw new Error(`Unknown part "${key}". Parts: ${known.join(", ")}.`);
+    }
+    const allowed = "options" in field ? (field.options as readonly string[]) : [];
+    if (!allowed.includes(value)) throw new Error(`Unknown ${key} "${value}". Choose one of: ${allowed.join(", ")}.`);
+    next[key] = value;
+  }
+  return schema.parse(next) as T;
+};
+
+const imageType = (bytes: Uint8Array): "png" | "jpeg" | "webp" | null => {
+  if (bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47) return "png";
+  if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return "jpeg";
+  if (String.fromCharCode(...bytes.slice(0, 4)) === "RIFF" && String.fromCharCode(...bytes.slice(8, 12)) === "WEBP") return "webp";
+  return null;
+};
+
+/** Reads a small square PNG, JPEG, or WebP as the data URL the API stores; the browser dialog crops, the CLI does not. */
+export const readAvatarPhoto = async (file: string): Promise<string> => {
+  const bytes = new Uint8Array(await readFile(file));
+  const type = imageType(bytes);
+  if (!type) throw new Error("The photo must be a PNG, JPEG, or WebP file.");
+  if (bytes.length > MAX_AVATAR_BYTES) {
+    throw new Error(
+      `The photo is ${Math.ceil(bytes.length / 1024)} KiB; the limit is ${MAX_AVATAR_BYTES / 1024} KiB. Crop and shrink it first.`,
+    );
+  }
+  return `data:image/${type};base64,${Buffer.from(bytes).toString("base64")}`;
+};

package/src/cli/capabilities.ts

@@ -16,6 +16,7 @@ import {
   cloudResourceRefAppId,
   resolveCapabilityResourceReader,
 } from "../contracts/capabilities";
+import { ResolvedCloudResourceUrlSchema } from "../contracts/resource-resolution";
 import { saveCapabilityStream } from "./capability-streams";
 import { arg, type CliInputFlagValue, type CloudCliContext, command, defineCliCommands, flag, readCliInput } from "./index";
 import { cloudResourceUrl } from "./resource-links";
@@ -139,7 +140,7 @@ const invoke = async (config: {
     }
     throw error;
   }
-  const result = capabilityResultSchema(z.unknown()).parse(body);
+  const result = capabilityResultSchema(z.unknown(), { consumer: true }).parse(body);
   const manifests = config.manifest ? [config.manifest] : [];
   const wantedApps = new Set((result.refs ?? []).map(cloudResourceRefAppId));
   for (const manifest of manifests) wantedApps.delete(manifest.appId);
@@ -179,6 +180,22 @@ export default defineCliCommands({
   name: "capabilities",
   summary: "Discover and invoke versioned Cloud app capabilities.",
   commands: [
+    command("resolve", {
+      summary: "Recognize a Cloud link and read its resource reference",
+      args: { url: arg.required({ description: "Cloud permalink or application page URL" }) },
+      run: async ({ ctx, args }) => {
+        const response = await ctx.fetch("/api/resources/resolve", {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ url: args.url.trim() }),
+        });
+        if (!response.ok) throw new Error("Resource not found.");
+        const body = await readBoundedJson(response, CAPABILITY_MAX_RESULT_BYTES);
+        if (!body.ok) throw new Error("Resource not found.");
+        const result = ResolvedCloudResourceUrlSchema.parse(body.data);
+        printGenericResult(ctx, { ...result, permalink: cloudResourceUrl(ctx, result.ref) });
+      },
+    }),
     ...(["read", "write", "status", "abort"] as const).map((verb) =>
       command(`stream-${verb}`, {
         summary: `${verb} an authenticated binary capability stream`,
@@ -247,6 +264,8 @@ export default defineCliCommands({
             types: app.manifest.types.length,
             queries: app.manifest.queries.length,
             actions: app.manifest.actions.length,
+            events: app.manifest.events?.length ?? 0,
+            subscribes: app.manifest.subscribes?.length ?? 0,
           })),
           [
             { key: "app", label: "APP" },
@@ -254,6 +273,8 @@ export default defineCliCommands({
             { key: "types", label: "TYPES" },
             { key: "queries", label: "QUERIES" },
             { key: "actions", label: "ACTIONS" },
+            { key: "events", label: "EVENTS" },
+            { key: "subscribes", label: "SUBSCRIBES" },
           ],
         );
         if (result.page.hasMore) ctx.error(`More apps available; continue with --cursor ${result.page.nextCursor}`);

package/src/cli/events.ts

@@ -0,0 +1,320 @@
+import { link, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { z } from "zod";
+import { assertAppEventSize } from "../_internal/app-event-schemas";
+import { APP_EVENT_MAX_BYTES, AppEventEnvelopeSchema, appEventSubscriptionId } from "../contracts/app-events";
+import { CapabilityQualifiedIdSchema } from "../contracts/capabilities";
+import { arg, command, confirmFlag, defineCliCommands, flag } from "./commands";
+import type { CloudCliContext } from "./index";
+import { localizeCloudCliText } from "./locale";
+import { printRows, printStructured } from "./output";
+
+const API = "/api/app-events";
+const catalogSchema = z.object({
+  events: z.array(
+    z.object({
+      type: CapabilityQualifiedIdSchema,
+      version: z.number().int().positive(),
+      title: z.string(),
+      description: z.string(),
+      subject: CapabilityQualifiedIdSchema,
+      place: CapabilityQualifiedIdSchema.nullable(),
+      automation: z.boolean(),
+      dataSchema: z.record(z.string(), z.unknown()),
+      subscribers: z.array(z.unknown()),
+    }),
+  ),
+});
+
+const read = async <T>(ctx: CloudCliContext, path: string, init?: RequestInit) => ctx.readJson<T>(await ctx.fetch(`${API}${path}`, init));
+const catalog = async (ctx: CloudCliContext) => catalogSchema.parse(await read(ctx, "/catalog"));
+
+// Consume one bounded envelope at a time, including when the input has no newline.
+async function* jsonLines(stream: ReadableStream<Uint8Array>, locale?: string, maxBytes?: number) {
+  const t = (en: string, de: string) => localizeCloudCliText(locale, { en, de });
+  const reader = stream.getReader();
+  let pending = new Uint8Array(0);
+  let line = 0;
+  let bytesRead = 0;
+  const decode = (bytes: Uint8Array) => {
+    line++;
+    try {
+      const envelope = AppEventEnvelopeSchema.parse(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)));
+      assertAppEventSize(envelope);
+      return envelope;
+    } catch (cause) {
+      throw new Error(t(`Invalid event fixture at line ${line}.`, `Ungültige Event-Fixture in Zeile ${line}.`), { cause });
+    }
+  };
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      bytesRead += value.byteLength;
+      if (maxBytes !== undefined && bytesRead > maxBytes) {
+        throw new Error(
+          t("Fixture response exceeds the requested recording budget.", "Die Fixture-Antwort überschreitet das Aufnahmebudget."),
+        );
+      }
+      let start = 0;
+      for (let index = 0; index <= value.length; index++) {
+        if (index < value.length && value[index] !== 10) continue;
+        const part = value.subarray(start, index);
+        if (pending.length + part.length > APP_EVENT_MAX_BYTES) {
+          throw new Error(
+            t(
+              `Event fixture line ${line + 1} exceeds ${APP_EVENT_MAX_BYTES} bytes.`,
+              `Event-Fixture in Zeile ${line + 1} überschreitet ${APP_EVENT_MAX_BYTES} Bytes.`,
+            ),
+          );
+        }
+        const next = new Uint8Array(pending.length + part.length);
+        next.set(pending);
+        next.set(part, pending.length);
+        pending = next;
+        if (index < value.length) {
+          if (pending.length) yield decode(pending);
+          else line++;
+          pending = new Uint8Array(0);
+        }
+        start = index + 1;
+      }
+    }
+    if (pending.length) yield decode(pending);
+  } finally {
+    await reader.cancel();
+    reader.releaseLock();
+  }
+}
+
+const build = (locale?: string) => {
+  const t = (en: string, de: string) => localizeCloudCliText(locale, { en, de });
+  const print = (ctx: CloudCliContext, value: unknown) => {
+    if (!printStructured(ctx, value)) ctx.print(JSON.stringify(value, null, 2));
+  };
+  return defineCliCommands({
+    name: "events",
+    summary: t("Inspect declared app events and test local handlers.", "Deklarierte App-Events prüfen und lokale Handler testen."),
+    commands: [
+      command("ls", {
+        summary: t("List declared event types", "Deklarierte Event-Typen auflisten"),
+        flags: {
+          app: flag.string({ description: t("Publisher application ID", "ID der veröffentlichenden Anwendung") }),
+          automation: flag.enum(["true", "false"], {
+            description: t("Filter by automation metadata", "Nach Automationsmetadaten filtern"),
+          }),
+        },
+        async run({ ctx, flags }) {
+          const result = await catalog(ctx);
+          const events = result.events.filter(
+            (event) =>
+              (!flags.app || event.type.startsWith(`${flags.app}.`)) &&
+              (flags.automation === undefined || event.automation === (flags.automation === "true")),
+          );
+          printRows(ctx, { events }, events, [
+            { key: "type", label: "TYPE" },
+            { key: "version", label: "VERSION" },
+            { key: "title", label: t("TITLE", "TITEL") },
+            { key: "subject", label: "SUBJECT" },
+            { key: "place", label: "PLACE", value: (event) => event.place ?? "—" },
+            { key: "automation", label: "AUTOMATION", value: (event) => (event.automation ? t("yes", "ja") : t("no", "nein")) },
+          ]);
+        },
+      }),
+      command("subscriptions", {
+        summary: t("Inspect subscriptions and blocked reasons", "Abonnements und Sperrgründe prüfen"),
+        flags: { app: flag.string({ description: t("Subscriber application ID", "ID der abonnierenden Anwendung") }) },
+        run: async ({ ctx, flags }) =>
+          print(ctx, await read(ctx, `/subscriptions${flags.app ? `?${new URLSearchParams({ app: flags.app })}` : ""}`)),
+      }),
+      command("status", {
+        summary: t("Show event broker status and rejected events", "Status des Event-Brokers und abgelehnte Events anzeigen"),
+        run: async ({ ctx }) => print(ctx, await read(ctx, "/status")),
+      }),
+      command("deliveries", {
+        summary: t("List event deliveries", "Event-Zustellungen auflisten"),
+        flags: {
+          app: flag.string({ description: t("Subscriber application ID", "ID der abonnierenden Anwendung") }),
+          state: flag.string({ description: t("Delivery state", "Zustellstatus") }),
+          eventType: flag.string({ description: t("Qualified event type", "Vollständiger Event-Typ") }),
+          offset: flag.int({ default: 0, min: 0, description: t("Pagination offset", "Startposition der Seite") }),
+          limit: flag.int({ default: 50, min: 1, max: 100, description: t("Maximum deliveries", "Maximale Anzahl Zustellungen") }),
+        },
+        async run({ ctx, flags }) {
+          const query = new URLSearchParams({ offset: String(flags.offset), limit: String(flags.limit) });
+          for (const key of ["app", "state", "eventType"] as const) if (flags[key]) query.set(key, flags[key]);
+          const result = await read<{
+            items: Record<string, unknown>[];
+            pagination: { offset: number; limit: number; total: number };
+          }>(ctx, `/deliveries?${query}`);
+          printRows(ctx, result, result.items, [
+            { key: "id", label: "ID" },
+            { key: "subscriptionId", label: "SUBSCRIPTION" },
+            { key: "state", label: t("STATE", "STATUS") },
+            { key: "attempts", label: t("ATTEMPTS", "VERSUCHE") },
+            { key: "heldBy", label: t("HELD BY", "WARTET AUF") },
+          ]);
+        },
+      }),
+      command("redeliver", {
+        summary: t("Redeliver one retained delivery", "Eine gespeicherte Zustellung erneut ausführen"),
+        args: { id: arg.required({ description: t("Delivery ID", "Zustellungs-ID") }) },
+        flags: { yes: confirmFlag() },
+        async run({ ctx, args, flags }) {
+          if (!flags.yes) {
+            throw new Error(
+              t(
+                "Pass --yes to redeliver; the handler may repeat effects.",
+                "Für die erneute Zustellung --yes angeben; der Handler kann Effekte wiederholen.",
+              ),
+            );
+          }
+          print(ctx, await read(ctx, `/deliveries/${encodeURIComponent(args.id)}/redeliver`, { method: "POST" }));
+        },
+      }),
+      command("acknowledge-gap", {
+        summary: t("Acknowledge a reconciled retention gap", "Eine abgeglichene Retention-Lücke bestätigen"),
+        flags: { yes: confirmFlag() },
+        async run({ ctx, flags }) {
+          if (!flags.yes)
+            throw new Error(
+              t("Pass --yes after reconciling affected subscribers.", "Nach dem Abgleich betroffener Abonnenten --yes angeben."),
+            );
+          print(ctx, await read(ctx, "/status/acknowledge", { method: "POST" }));
+        },
+      }),
+      command("record", {
+        summary: t("Export shape-only JSONL fixtures", "JSONL-Fixtures nur mit synthetischen Daten exportieren"),
+        args: { eventType: arg.required({ description: t("Qualified event type", "Vollständiger Event-Typ") }) },
+        flags: {
+          shapeOnly: flag.boolean({
+            description: t("Required: generate synthetic fixture data", "Erforderlich: synthetische Fixture-Daten erzeugen"),
+          }),
+          limit: flag.int({
+            default: 10,
+            min: 1,
+            max: 100,
+            description: t("Recent events to inspect for distinct shapes", "Neueste Events für unterschiedliche Strukturen prüfen"),
+          }),
+          out: flag.string({ description: t("Create a JSONL file", "JSONL-Datei erstellen") }),
+        },
+        async run({ ctx, args, flags }) {
+          if (!flags.shapeOnly) throw new Error(t("record requires --shape-only.", "record erfordert --shape-only."));
+          const query = new URLSearchParams({ shapeOnly: "true", limit: String(flags.limit) });
+          const response = await ctx.fetch(`${API}/record/${encodeURIComponent(args.eventType)}?${query}`);
+          if (!response.ok) {
+            await ctx.readJson(response);
+            return;
+          }
+          if (!response.body) throw new Error(t("Cloud returned no fixture stream.", "Cloud hat keinen Fixture-Stream geliefert."));
+          const fixtures = [];
+          for await (const envelope of jsonLines(response.body, locale, flags.limit! * (APP_EVENT_MAX_BYTES + 1))) {
+            if (fixtures.length >= flags.limit!) {
+              throw new Error(t("Cloud returned too many fixtures.", "Cloud hat zu viele Fixtures geliefert."));
+            }
+            if (envelope.type !== args.eventType) {
+              throw new Error(t("Cloud returned a different event type.", "Cloud hat einen anderen Event-Typ geliefert."));
+            }
+            fixtures.push(envelope);
+          }
+          if (flags.out) {
+            const path = resolve(flags.out);
+            const temporary = await mkdtemp(join(dirname(path), ".cloud-event-fixtures-"));
+            try {
+              const part = join(temporary, "fixtures.jsonl");
+              await writeFile(part, fixtures.map((event) => JSON.stringify(event)).join("\n") + (fixtures.length ? "\n" : ""), {
+                mode: 0o600,
+              });
+              await link(part, path);
+            } finally {
+              await rm(temporary, { recursive: true, force: true });
+            }
+            print(ctx, { path, count: fixtures.length });
+          } else if (ctx.options.output === "json") ctx.json(fixtures);
+          else for (const fixture of fixtures) await ctx.write(`${JSON.stringify(fixture)}\n`);
+        },
+      }),
+      command("replay", {
+        summary: t("Replay fixtures into a local handler", "Fixtures an einen lokalen Handler übergeben"),
+        args: { fixtures: arg.required({ description: t("JSONL fixture file", "JSONL-Fixture-Datei") }) },
+        flags: {
+          handler: flag.string({
+            required: true,
+            description: t("Local module path[#export], default export by default", "Lokaler Modulpfad[#export], sonst Default-Export"),
+          }),
+        },
+        async run({ ctx, args, flags }) {
+          const current = await catalog(ctx);
+          const declarations = new Map(current.events.map((event) => [event.type, event]));
+          const validators = new Map<string, z.ZodType>();
+          const [modulePath, exportName = "default", ...extra] = flags.handler!.split("#");
+          if (!modulePath || !exportName || extra.length) {
+            throw new Error(t("Use a local path[#export] for --handler.", "Für --handler einen lokalen Pfad[#export] angeben."));
+          }
+          const module: Record<string, unknown> = await import(pathToFileURL(resolve(modulePath)).href);
+          const handler = module[exportName];
+          if (typeof handler !== "function") {
+            throw new Error(t("The selected handler export must be a function.", "Der gewählte Handler-Export muss eine Funktion sein."));
+          }
+          let delivered = 0;
+          try {
+            for await (const envelope of jsonLines(Bun.file(resolve(args.fixtures)).stream(), locale)) {
+              const event = declarations.get(envelope.type);
+              if (!event || event.version !== envelope.version) {
+                throw new Error(
+                  t(
+                    `Event ${envelope.type}@${envelope.version} is absent from the current catalog.`,
+                    `Event ${envelope.type}@${envelope.version} fehlt im aktuellen Katalog.`,
+                  ),
+                );
+              }
+              if (
+                envelope.source !== envelope.type.split(".")[0] ||
+                envelope.subject.type !== event.subject ||
+                (envelope.place?.type ?? null) !== event.place
+              ) {
+                throw new Error(
+                  t(
+                    `Event ${envelope.type} references do not match the current catalog.`,
+                    `Referenzen von Event ${envelope.type} passen nicht zum aktuellen Katalog.`,
+                  ),
+                );
+              }
+              let validator = validators.get(envelope.type);
+              if (!validator) {
+                validator = z.fromJSONSchema(structuredClone(event.dataSchema));
+                validators.set(envelope.type, validator);
+              }
+              validator.parse(envelope.data);
+              await handler(envelope, {
+                subscriptionId: appEventSubscriptionId("replay", envelope.type, envelope.version),
+                eventId: envelope.id,
+                attempt: 1,
+                signal: new AbortController().signal,
+              });
+              delivered++;
+            }
+          } catch (cause) {
+            const detail = cause instanceof Error ? cause.message : String(cause);
+            throw new Error(
+              t(
+                `Replay stopped after ${delivered} completed fixtures: ${detail}`,
+                `Replay wurde nach ${delivered} abgeschlossenen Fixtures angehalten: ${detail}`,
+              ),
+              { cause },
+            );
+          }
+          print(ctx, { delivered });
+        },
+      }),
+    ],
+  });
+};
+
+const eventsCliModule = build();
+export default {
+  ...eventsCliModule,
+  help: (locale?: string) => build(locale).help?.(locale) ?? "",
+  run: (ctx: CloudCliContext) => build(ctx.options.locale).run(ctx),
+};

package/src/cli/index.ts

@@ -96,9 +96,9 @@ export type CloudCliModule = {
 
 export * from "./access";
 export * from "./address";
+export { createAppAccessCommands } from "./app-access";
 export * from "./commands";
 export * from "./locale";
 export * from "./output";
 export * from "./plugin";
-
 export * from "./resource-links";

package/src/config/env.ts

@@ -10,6 +10,17 @@ const syncReplicas = z
   .enum(["1", "3", "5"], { error: "must be 1, 3, or 5" })
   .transform((value): 1 | 3 | 5 => (value === "1" ? 1 : value === "3" ? 3 : 5));
 
+const budgetSchema = z
+  .object({
+    maxStepsPerSource: z.number().int().positive(),
+    tasksPerMinute: z.number().int().positive(),
+    burst: z.number().int().positive(),
+    sourcesPer24Hours: z.number().int().positive(),
+    scopeConcurrent: z.number().int().positive(),
+    globalConcurrent: z.number().int().positive(),
+  })
+  .strict();
+
 const registry = defineEnv({
   // Process
   NODE_ENV: {
@@ -66,6 +77,35 @@ const registry = defineEnv({
     doc: "Only dial the listed servers and ignore cluster-advertised peer addresses; set to `false` when every advertised address is reachable.",
   },
 
+  WORKFLOW_AI_BUDGET: {
+    schema: z
+      .string()
+      .transform((value, ctx) => {
+        try {
+          return JSON.parse(value);
+        } catch {
+          ctx.addIssue({ code: "custom", message: "must be JSON" });
+          return z.NEVER;
+        }
+      })
+      .pipe(budgetSchema),
+    default: { maxStepsPerSource: 2, tasksPerMinute: 10, burst: 20, sourcesPer24Hours: 2_000, scopeConcurrent: 1, globalConcurrent: 4 },
+    doc: "JSON scoped workflow inference budget: active or successful logical requests per source/24h, token-bucket admission per minute and burst, distinct sources per rolling 24h, outstanding tasks per scope and globally; capacity/rate overload uses bounded workflow retries, daily/source limits fail visibly, and cache hits consume no reservation.",
+  },
+
+  // Workflow inference: p95 ~4s in the pilot; 60s bounds a whole attempt,
+  // including admission and structured-output repair, not just stream idleness.
+  WORKFLOW_AI_ATTEMPT_TIMEOUT_MS: {
+    schema: z.coerce.number().int().positive(),
+    default: 60_000,
+    doc: "Absolute workflow AI attempt budget in milliseconds, including admission and repair; expiry aborts the provider and follows the bounded retry policy.",
+  },
+  WORKFLOW_AI_QUEUE_TIMEOUT_MS: {
+    schema: z.coerce.number().int().positive(),
+    default: 60_000,
+    doc: "Maximum workflow AI queue wait in milliseconds; recovery fails overdue or lost deliveries visibly so an operator can retry the workflow.",
+  },
+
   // Installation
   APP_URL: {
     schema: z.string(),