feat(realtime): add realtime command and handler scaffolding

[ImriKochWix]

Note

Description

Adds first-class support for realtime handlers to the Base44 CLI. Introduces a new realtime resource (scaffold, config discovery, deploy) plus a base44 realtime command group (new, deploy), wires realtime handlers into the unified base44 deploy flow, and extends TypeScript type generation to emit strongly-typed message catalogs (RealtimeHandlerRegistry, RealtimeHandlerNameRegistry) from each handler's schema.jsonc.

Related Issue

None

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Other (please describe):

Changes Made

• New realtime-handler core resource (src/core/resources/realtime-handler/): schema.ts (Zod schemas for config, message catalog, and deploy response), config.ts (discovers entry.ts handlers in named subfolders, reads optional schema.jsonc, guards against duplicate/misplaced handlers), api.ts (PUT to /realtime-handlers/{name}), deploy.ts (sequential deploy with per-handler status reporting), and resource.ts (unified Resource binding).
• New base44 realtime command group (src/cli/commands/realtime/): new <HandlerName> scaffolds a RealtimeHandler class extending @base44/sdk, and deploy [names...] deploys selected or all handlers with progress output and non-zero exit on failure.
• Project config integration: added realtimeDir (default \"realtime\") to the project config schema, realtimeHandlers to ProjectData, and read/deploy wiring in config.ts, deploy.ts, and the top-level deploy command summary.
• Type generation: compiles each handler's message catalog (types / toClient / toServer) in a single pass into named interfaces and discriminated unions, injecting the type discriminant per message and rewriting #/types/X refs; emits RealtimeHandlerRegistry and RealtimeHandlerNameRegistry. Also detects the SDK package name (@base44/sdk vs @base44-preview/sdk) and adds export {}; so the generated types.d.ts augments rather than replaces the SDK module.
• Tests & fixtures: added tests/core/types-realtime.spec.ts, updated tests/cli/types_generate.spec.ts, and added a ChatRoom realtime fixture (entry.ts + schema.jsonc).

Testing

• I have tested these changes locally
• I have added/updated tests as needed
• All tests pass (`npm test`)

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation (if applicable)
• My changes generate no new warnings
• I have updated `docs/` (AGENTS.md) if I made architectural changes

Additional Notes

The realtime resource mirrors the existing function resource conventions (multi-file payloads, sequential deploy, Resource<T> interface) for consistency. Handler message schemas use a toClient/toServer naming convention (renamed from an earlier inbound/outbound within this PR). Consider adding a docs/ topic guide and updating AGENTS.md to document the new resource before release.

---

_{🤖 Generated by Claude | 2026-07-05 21:30 UTC | 77b65cb}

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/cli@0.1.1-pr.555.77b65cb

Prefer not to change any import paths? Install using npm alias so your code still imports base44:

npm i "base44@npm:@base44-preview/cli@0.1.1-pr.555.77b65cb"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "base44": "npm:@base44-preview/cli@0.1.1-pr.555.77b65cb"
  }
}

• 📦 Preview Package: @base44-preview/cli@0.1.1-pr.555.77b65cb
• 🔗 View this commit on GitHub

---

_{Preview published to npm registry — try new features instantly!}