feat(actor): add actor command and scaffolding

[ImriKochWix]

Note

Description

Adds a new actor resource to the CLI (formerly "realtime handler"), enabling users to scaffold, deploy, and type-check stateful realtime actors from the terminal. Actors live in base44/actors/<Name>/ with an entry.ts and optional schema.jsonc message catalog, and are wired into project config, the unified deploy command, and TypeScript type generation. Also pins npm@11 in the publish workflows to fix an EBADENGINE failure on the Node 20 runner.

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): CI fix — pin npm@11 in publish workflows

Changes Made

• New actor resource (core/resources/actor/): schema, config reader (readAllActors), deploy logic (deployActorsSequentially → PUT actors/<name>), API client, and Resource<Actor> binding.
• New CLI commands under base44 actor: new <ActorName> scaffolds an Actor<State, Message> subclass, and deploy [names...] deploys selected or all actors with per-actor status (deployed/unchanged/error) and a summary.
• Project integration: added actorsDir (default actors) to the config schema, threaded actors through ProjectData, readProjectConfig, hasResourcesToDeploy, and deployAll so the unified deploy command handles actors.
• Type generation: schema.jsonc message catalogs (types/toClient/toServer) compile into an ActorRegistry discriminated union plus an ActorNameRegistry, replacing the old regex-based extraction with a single-pass compile; SDK package name (@base44/sdk vs @base44-preview/sdk) is auto-detected and a module context guard (export {};) is emitted.
• Rename: realtime / RealtimeHandler renamed to actor / Actor throughout; schema sections renamed inbound/outbound → toClient/toServer.
• CI: pinned npm@11 in manual-publish.yml and preview-publish.yml (npm@latest is 12.x, requires Node >=22).

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

New tests added: tests/core/types-actor.spec.ts (catalog → discriminated union compilation, shared-type prefixing, name-collision detection) and extended tests/cli/types_generate.spec.ts with ActorNameRegistry/ActorRegistry assertions plus a ChatRoom fixture. Since actors are a new backend resource type, docs/resources.md may warrant an update.

---

_{🤖 Generated by Claude | 2026-07-09 13:35 UTC | 3443d0b}

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/cli@0.1.2-pr.555.3443d0b

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.2-pr.555.3443d0b"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "base44": "npm:@base44-preview/cli@0.1.2-pr.555.3443d0b"
  }
}

• 📦 Preview Package: @base44-preview/cli@0.1.2-pr.555.3443d0b
• 🔗 View this commit on GitHub

---

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