feat: Client-published events + realtime presence

- POST /projects/:id/events accepts client-authored events restricted to
  the custom.* namespace — system types can't be spoofed. They flow
  through the same publishEvent fan-out: realtime, webhooks, and
  event_pattern functions all fire.
- Presence: subscribe/unsubscribe bumps a per-project count and
  broadcasts presence.update {online} to the realtime stream only —
  deliberately not through publishEvent so webhooks and "*" functions
  don't fire on connect noise. GET …/realtime/presence reads the count.
- @primora/client gains publish() and presence(); CLI gains events:send.

Verified live: presence 0->1 on subscribe, presence.update frame
delivered, custom event delivered to SSE + fired a custom.* function,
spoofed document.created rejected 400.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

apps/cli/README.md

@@ -21,7 +21,14 @@ project interactively.
 ## Commands
 
 `orgs`, `projects`, `buckets`, `objects` (list/upload/download/rm), `keys`,
-`jobs`, `audit list --follow`. Every command accepts `--json`.
+`jobs`, `events:send`, `audit list --follow`. Every command accepts `--json`.
+
+```sh
+primora events:send custom.deploy.done --data '{"sha":"abc123"}'
+```
+
+`events:send` publishes a `custom.*` event — realtime subscribers, matching
+webhooks, and `event_pattern` functions all fire.
 
 ```sh
 primora documents list --collection users \

apps/cli/src/cli.ts

@@ -3,6 +3,7 @@ import { cac } from "cac";
 import { cmdLogin, cmdLogout, cmdWhoami } from "./commands/auth.js";
 import { cmdAuditList } from "./commands/audit.js";
 import { cmdDocumentsList } from "./commands/documents.js";
+import { cmdEventsSend } from "./commands/events.js";
 import { cmdBucketsCreate, cmdBucketsList } from "./commands/buckets.js";
 import { cmdContext, cmdUse } from "./commands/context.js";
 import { cmdInject } from "./commands/inject.js";
@@ -174,6 +175,12 @@ cli
   .option("--offset <n>", "Page offset")
   .action(cmdDocumentsList);
 
+cli
+  .command("events:send <type>", "Publish a custom.* event to realtime subscribers, webhooks, and functions")
+  .option("--project <id>", "Project override")
+  .option("--data <json>", "JSON object payload")
+  .action(cmdEventsSend);
+
 cli
   .command("audit:list", "List audit events for the current project")
   .option("--project <id>", "Project override")

apps/cli/src/commands/events.ts

@@ -0,0 +1,48 @@
+import { AutomationService } from "@primora/api-client";
+
+import { loadConfig } from "../config.js";
+import { CliError, configureClient, requireAuth, requireProject } from "../http.js";
+import { isJson, printJson } from "../out.js";
+
+interface EventsSendOptions {
+  project?: string;
+  data?: string;
+  json?: boolean;
+}
+
+export async function cmdEventsSend(type: string, options: EventsSendOptions): Promise<void> {
+  if (!type.startsWith("custom.")) {
+    throw new CliError(
+      `Invalid event type "${type}".`,
+      "Client events must live in the custom.* namespace — e.g. custom.deploy.done",
+    );
+  }
+  let data: Record<string, unknown> = {};
+  if (options.data) {
+    try {
+      const parsed = JSON.parse(options.data);
+      if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new CliError("--data must be a JSON object.", `Got: ${options.data.slice(0, 60)}`);
+      }
+      data = parsed;
+    } catch (e) {
+      if (e instanceof CliError) throw e;
+      throw new CliError("--data is not valid JSON.", (e as Error).message);
+    }
+  }
+
+  const cfg = loadConfig();
+  requireAuth(cfg);
+  configureClient(cfg);
+  const projectId = requireProject(cfg, options.project);
+
+  const res = await AutomationService.publishProjectEvent({
+    projectId,
+    requestBody: { type, data },
+  });
+  if (isJson(options)) {
+    printJson(res);
+    return;
+  }
+  console.log(`Published ${res.published ?? type} — realtime subscribers, matching webhooks, and event_pattern functions fire.`);
+}