feat(actor): add actor command and scaffolding

[ImriKochWix]

Note

Description

Adds actors as a first-class Base44 resource: stateful, long-lived server objects (prototyped earlier in this branch as "realtime handlers") that live in base44/actors/<ActorName>/entry.ts. The PR introduces a new base44 actor command group (new, deploy), wires actors into project config reading, unified base44 deploy, and TypeScript type generation. Actors can declare a schema.jsonc message catalog (types / toClient / toServer), which is compiled into a discriminated-union ActorRegistry so client and server message handling is fully typed.

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 the publish workflows

Changes Made

New actor resource (src/core/resources/actor/)

• schema.ts — Zod schemas for the actor config, the schema.jsonc message catalog (types / toClient / toServer), and the deploy response (deployed | unchanged)
• config.ts — discovers **/entry.{js,ts} under the actors dir, derives the actor name from its subfolder, loads the optional schema.jsonc, and rejects duplicate names or an entry.ts placed directly in the actors root
• api.ts — PUT actors/:name with the entry file plus all sibling .ts files, Zod-validated response, ApiError.fromHttpError() on failure
• deploy.ts — sequential per-actor deploy with onStart/onResult callbacks and per-actor timing; failures are captured per actor rather than aborting the run
• resource.ts — standard Resource<Actor> (readAll / push) so actors join the unified resource pipeline

CLI commands (src/cli/commands/actor/)

• base44 actor new <ActorName> — scaffolds base44/actors/<ActorName>/entry.ts with a typed Actor<State, Message> subclass that imports Actor from the virtual base44:runtime/actors module and Conn as a pure type from the SDK, then re-reads the project and regenerates base44/.types/types.d.ts (plus updateProjectConfig) so that import resolves in the editor immediately
• base44 actor deploy [names...] — deploys all actors or a comma/space-separated subset, prints per-actor status plus a summary, and exits 1 via CLIExitError if any actor fails
• Registered the actor command group in program.ts

Project integration

• Added actorsDir (default "actors") to ProjectConfigSchema, and actors to ProjectData / ProjectResources
• readProjectConfig() now reads actors in parallel with the other resources; plugin projects get an empty actor list
• hasResourcesToDeploy(), the base44 deploy summary, and deployAll() all account for actors
• base44 types generate passes actors through to the generator

Type generation (src/core/types/generator.ts)

• New ActorNameRegistry and ActorRegistry augmentations; each actor's message catalog compiles in a single json-schema-to-typescript pass into one named interface per message (direction-prefixed) plus shared types, with the type discriminant injected from the message key and #/types/X refs rewritten to prefixed $defs
• Throws TypeGenerationError on generated-name collisions instead of silently clobbering
• Emits declare module 'base44:runtime/actors' re-exporting only the Actor base class (pure types keep coming from the SDK)
• Detects @base44/sdk vs @base44-preview/sdk from the project package.json, and adds export {}; so the generated file is a module and declare module augments rather than replaces the SDK types
• Updated the empty-project template text to mention actors

CI

• Pinned npm@11 in manual-publish.yml and preview-publish.yml — npm@latest is now 12.x, which requires Node >= 22 and fails EBADENGINE on the Node 20 runner

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 unit tests in tests/core/types-actor.spec.ts cover catalog compilation (discriminant injection, shared-type reuse, registry union assembly, the base44:runtime/actors declaration) and the name-collision error. tests/cli/types_generate.spec.ts was extended with actor registry assertions plus a new ChatRoom fixture (entry.ts + schema.jsonc). The suite was not run while generating this description, so the "tested locally" / "all tests pass" boxes are left unchecked.
• Docs are not updated yet: docs/resources.md, docs/commands.md, and the README don't mention the new resource or the base44 actor commands — worth adding before merge, per rule 9 ("Keep docs updated").
• Actors deploy sequentially rather than in batches (unlike functions), so a project with many actors deploys more slowly.
• actor new reads the project config twice (once for paths, once after writing the scaffold) so type generation picks up the new actor.
• Earlier commits on this branch land the resource as realtime-handler / RealtimeHandler; it was renamed to actor / Actor later in the branch, and toClient / toServer replaced an earlier inbound / outbound pair. Only the final naming ships.

---

_{🤖 Generated by Claude | 2026-07-28 11:16 UTC | eaa386d}

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/cli@0.1.6-pr.555.eaa386d

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.6-pr.555.eaa386d"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "base44": "npm:@base44-preview/cli@0.1.6-pr.555.eaa386d"
  }
}

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

---

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