feat(realtime): add realtime command and handler scaffolding

[ImriKochWix]

Note

Description

This PR introduces a new realtime handler resource type to the Base44 CLI, letting developers create, manage, and deploy realtime (WebSocket-style) handlers from the terminal. Handlers live in a base44/realtime/ directory, are scaffolded with a typed RealtimeHandler base class, and deploy via a dedicated realtime-handlers API endpoint. Realtime handlers are wired into the unified deploy and types generate flows, and TypeScript types (including inbound/outbound message schemas) are auto-generated 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 (core/resources/realtime-handler/): schema, config discovery (readAllRealtimeHandlers), API client (deploySingleRealtimeHandler → PUT /realtime-handlers/{name}), sequential deploy logic, and a Resource<RealtimeHandler> implementation.
• New base44 realtime command group with new <HandlerName> (scaffolds a typed RealtimeHandler subclass under base44/realtime/) and deploy [names...] (deploys selected or all handlers with per-handler status reporting).
• Unified deploy integration: realtime handlers are now read, counted in the deploy summary, included in hasResourcesToDeploy, and pushed in deployAll.
• Project config: added realtimeDir (default realtime) to the config schema, ProjectData, and the config reader (including plugin/zero-config paths that default to empty arrays).
• Type generation: emits RealtimeHandlerNameRegistry and RealtimeHandlerRegistry (typed inbound/outbound message shapes compiled from each handler's schema.jsonc); added SDK package-name detection (@base44/sdk vs @base44-preview/sdk) and an export {} module marker so the declare module augments rather than replaces the SDK package.
• Tests & fixtures: extended the types generate spec and added a ChatRoom realtime handler 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

A new resource type was added without a corresponding topic guide in docs/; consider documenting the realtime handler resource and the base44 realtime command group to keep docs/ in sync with the architecture.

---

_{🤖 Generated by Claude | 2026-06-30 13:15 UTC | c9c117a}

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/cli@0.1.1-pr.555.c9c117a

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.c9c117a"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "base44": "npm:@base44-preview/cli@0.1.1-pr.555.c9c117a"
  }
}

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

---

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