feat(actor): add actor command and scaffolding

.github/workflows/manual-publish.yml

@@ -53,7 +53,9 @@ jobs:
           registry-url: "https://registry.npmjs.org"
 
       - name: Update npm
-        run: npm install -g npm@latest
+        # Pin npm@11: npm@latest is now 12.x (needs node >=22) and fails
+        # EBADENGINE on the node-20 runner (.node-version). npm 11 supports node ^20.17.
+        run: npm install -g npm@11
 
       - name: Setup Bun
         id: setup-bun

.github/workflows/preview-publish.yml

@@ -22,7 +22,9 @@ jobs:
           registry-url: "https://registry.npmjs.org"
 
       - name: Update npm
-        run: npm install -g npm@latest
+        # Pin npm@11: npm@latest is now 12.x (needs node >=22) and fails
+        # EBADENGINE on the node-20 runner (.node-version). npm 11 supports node ^20.17.
+        run: npm install -g npm@11
         working-directory: .
 
       - name: Setup Bun

packages/cli/src/cli/commands/actor/deploy.ts

@@ -0,0 +1,113 @@
+import type { Logger } from "@base44-cli/logger";
+import type { Command } from "commander";
+import { CLIExitError } from "@/cli/errors.js";
+import type { CLIContext, RunCommandResult } from "@/cli/types.js";
+import { Base44Command, theme } from "@/cli/utils/index.js";
+import { InvalidInputError } from "@/core/errors.js";
+import { readProjectConfig } from "@/core/index.js";
+import {
+  deployActorsSequentially,
+  type SingleActorDeployResult,
+} from "@/core/resources/actor/deploy.js";
+import type { Actor } from "@/core/resources/actor/schema.js";
+
+function parseNames(args: string[]): string[] {
+  return args
+    .flatMap((arg) => arg.split(","))
+    .map((n) => n.trim())
+    .filter(Boolean);
+}
+
+function resolveActorsToDeploy(names: string[], allActors: Actor[]): Actor[] {
+  if (names.length === 0) return allActors;
+
+  const notFound = names.filter((n) => !allActors.some((a) => a.name === n));
+  if (notFound.length > 0) {
+    throw new InvalidInputError(
+      `Actor${notFound.length > 1 ? "s" : ""} not found in project: ${notFound.join(", ")}`,
+    );
+  }
+  return allActors.filter((a) => names.includes(a.name));
+}
+
+function formatDeployResult(
+  result: SingleActorDeployResult,
+  log: Logger,
+): void {
+  const label = result.name.padEnd(25);
+  if (result.status === "deployed") {
+    const timing = result.durationMs
+      ? theme.styles.dim(` (${(result.durationMs / 1000).toFixed(1)}s)`)
+      : "";
+    log.success(`${label} deployed${timing}`);
+  } else if (result.status === "unchanged") {
+    log.success(`${label} unchanged`);
+  } else {
+    log.error(`${label} error: ${result.error}`);
+  }
+}
+
+function buildDeploySummary(results: SingleActorDeployResult[]): string {
+  const deployed = results.filter((r) => r.status === "deployed").length;
+  const unchanged = results.filter((r) => r.status === "unchanged").length;
+  const failed = results.filter((r) => r.status === "error").length;
+
+  const parts: string[] = [];
+  if (deployed > 0) parts.push(`${deployed} deployed`);
+  if (unchanged > 0) parts.push(`${unchanged} unchanged`);
+  if (failed > 0) parts.push(`${failed} error${failed !== 1 ? "s" : ""}`);
+  return parts.join(", ") || "No actors deployed";
+}
+
+async function deployActorAction(
+  { log }: CLIContext,
+  names: string[],
+): Promise<RunCommandResult> {
+  const { actors } = await readProjectConfig();
+  const toDeploy = resolveActorsToDeploy(names, actors);
+
+  if (toDeploy.length === 0) {
+    return {
+      outroMessage: "No actors found. Create actors in the 'actors' directory.",
+    };
+  }
+
+  log.info(
+    `Found ${toDeploy.length} ${toDeploy.length === 1 ? "actor" : "actors"} to deploy`,
+  );
+
+  let completed = 0;
+  const total = toDeploy.length;
+
+  const results = await deployActorsSequentially(toDeploy, {
+    onStart: (startNames) => {
+      const label =
+        startNames.length === 1 ? startNames[0] : `${startNames.length} actors`;
+      log.step(
+        theme.styles.dim(`[${completed + 1}/${total}] Deploying ${label}...`),
+      );
+    },
+    onResult: (result) => {
+      completed++;
+      formatDeployResult(result, log);
+    },
+  });
+
+  const hasFailures = results.some((r) => r.status === "error");
+  if (hasFailures) {
+    log.message(buildDeploySummary(results));
+    throw new CLIExitError(1);
+  }
+
+  return { outroMessage: buildDeploySummary(results) };
+}
+
+export function getDeployCommand(): Command {
+  return new Base44Command("deploy")
+    .description("Deploy actors to Base44")
+    .argument("[names...]", "Actor names to deploy (deploys all if omitted)")
+    .action(async (ctx: CLIContext, rawNames: string[]) => {
+      const names = parseNames(rawNames);
+      return deployActorAction(ctx, names);
+    });
+}

packages/cli/src/cli/commands/actor/index.ts

@@ -0,0 +1,10 @@
+import { Command } from "commander";
+import { getDeployCommand } from "./deploy.js";
+import { getNewCommand } from "./new.js";
+
+export function getActorCommand(): Command {
+  return new Command("actor")
+    .description("Manage actors")
+    .addCommand(getNewCommand())
+    .addCommand(getDeployCommand());
+}

packages/cli/src/cli/commands/actor/new.ts

@@ -0,0 +1,62 @@
+import { dirname, join } from "node:path";
+import type { Command } from "commander";
+import type { CLIContext, RunCommandResult } from "@/cli/types.js";
+import { Base44Command } from "@/cli/utils/index.js";
+import { InvalidInputError } from "@/core/errors.js";
+import { readProjectConfig } from "@/core/index.js";
+import { pathExists, writeFile } from "@/core/utils/fs.js";
+
+function buildActorScaffold(actorName: string): string {
+  return `import { Actor, type Conn } from "@base44/sdk";
+
+interface State {
+  // shared state broadcast to all clients
+}
+
+interface Message {
+  // messages sent from clients
+}
+
+export class ${actorName} extends Actor<State, Message> {
+  handleConnect(conn: Conn) {
+    console.log("Connected:", conn.userId);
+  }
+  handleMessage(conn: Conn, msg: Message) {
+    console.log("Message:", msg);
+  }
+  handleTick() {}
+  handleClose(conn: Conn) {}
+}
+`;
+}
+
+async function newActorAction(
+  _ctx: CLIContext,
+  actorName: string,
+): Promise<RunCommandResult> {
+  const { project } = await readProjectConfig();
+  const actorsDir = join(dirname(project.configPath), project.actorsDir);
+  const actorDir = join(actorsDir, actorName);
+
+  if (await pathExists(actorDir)) {
+    throw new InvalidInputError(
+      `Actor "${actorName}" already exists at ${actorDir}`,
+    );
+  }
+
+  const entryPath = join(actorDir, "entry.ts");
+  await writeFile(entryPath, buildActorScaffold(actorName));
+
+  return {
+    outroMessage: `Created actor "${actorName}" at ${entryPath}`,
+  };
+}
+
+export function getNewCommand(): Command {
+  return new Base44Command("new")
+    .description("Create a new actor scaffold")
+    .argument("<ActorName>", "Name of the actor class")
+    .action(async (ctx: CLIContext, actorName: string) => {
+      return newActorAction(ctx, actorName);
+    });
+}

packages/cli/src/cli/commands/project/deploy.ts

@@ -45,8 +45,15 @@ export async function deployAction(
     };
   }
 
-  const { project, entities, functions, agents, connectors, authConfig } =
-    projectData;
+  const {
+    project,
+    entities,
+    functions,
+    actors,
+    agents,
+    connectors,
+    authConfig,
+  } = projectData;
 
   // Build summary of what will be deployed
   const summaryLines: string[] = [];
@@ -60,6 +67,11 @@ export async function deployAction(
       `  - ${functions.length} ${functions.length === 1 ? "function" : "functions"}`,
     );
   }
+  if (actors.length > 0) {
+    summaryLines.push(
+      `  - ${actors.length} ${actors.length === 1 ? "actor" : "actors"}`,
+    );
+  }
   if (agents.length > 0) {
     summaryLines.push(
       `  - ${agents.length} ${agents.length === 1 ? "agent" : "agents"}`,

packages/cli/src/cli/commands/types/generate.ts

@@ -9,7 +9,7 @@ const TYPES_FILE_PATH = "base44/.types/types.d.ts";
 async function generateTypesAction({
   runTask,
 }: CLIContext): Promise<RunCommandResult> {
-  const { entities, functions, agents, connectors, project } =
+  const { entities, functions, agents, connectors, actors, project } =
     await readProjectConfig();
 
   await runTask("Generating types", async () => {
@@ -19,6 +19,7 @@ async function generateTypesAction({
       functions,
       agents,
       connectors,
+      actors,
     });
   });
 

packages/cli/src/cli/program.ts

@@ -1,4 +1,5 @@
 import { Command, Option } from "commander";
+import { getActorCommand } from "@/cli/commands/actor/index.js";
 import { getAgentsCommand } from "@/cli/commands/agents/index.js";
 import { getAuthCommand } from "@/cli/commands/auth/index.js";
 import { getLoginCommand } from "@/cli/commands/auth/login.js";
@@ -82,6 +83,9 @@ export function createProgram(context: CLIContext): Command {
   // Register functions commands
   program.addCommand(getFunctionsCommand());
 
+  // Register actor commands
+  program.addCommand(getActorCommand());
+
   // Register secrets commands
   program.addCommand(getSecretsCommand());
 

packages/cli/src/core/project/config.ts

@@ -18,6 +18,7 @@ import {
   ProjectConfigSchema,
 } from "@/core/project/schema.js";
 import type { ProjectData, ProjectRoot } from "@/core/project/types.js";
+import { actorResource } from "@/core/resources/actor/index.js";
 import { agentResource } from "@/core/resources/agent/index.js";
 import { authConfigResource } from "@/core/resources/auth-config/index.js";
 import { connectorResource } from "@/core/resources/connector/index.js";
@@ -60,6 +61,7 @@ class ProjectConfigReader {
       project: { ...project, root, configPath },
       entities,
       functions,
+      actors: localResources.actors,
       agents: localResources.agents,
       connectors: localResources.connectors,
       authConfig: localResources.authConfig,
@@ -105,16 +107,24 @@ class ProjectConfigReader {
     project: ProjectConfig,
   ): Promise<ProjectResources> {
     const configDir = dirname(configPath);
-    const [entities, functions, agents, connectors, authConfig] =
+    const [entities, functions, actors, agents, connectors, authConfig] =
       await Promise.all([
         entityResource.readAll(join(configDir, project.entitiesDir)),
         functionResource.readAll(join(configDir, project.functionsDir)),
+        actorResource.readAll(join(configDir, project.actorsDir)),
         agentResource.readAll(join(configDir, project.agentsDir)),
         connectorResource.readAll(join(configDir, project.connectorsDir)),
         authConfigResource.readAll(join(configDir, project.authDir)),
       ]);
 
-    return { entities, functions, agents, connectors, authConfig };
+    return {
+      entities,
+      functions,
+      actors,
+      agents,
+      connectors,
+      authConfig,
+    };
   }
 
   private assertPluginProjectDoesNotLoadPlugins(
@@ -184,6 +194,7 @@ class ProjectConfigReader {
     return {
       entities: markPluginEntities(resources.entities, namespace),
       functions: namespacePluginFunctions(resources.functions, namespace),
+      actors: [],
       agents: [],
       connectors: [],
       authConfig: [],
@@ -240,6 +251,7 @@ class ProjectConfigReader {
     return {
       entities,
       functions,
+      actors: [],
       agents: [],
       connectors: [],
       authConfig: [],

packages/cli/src/core/project/deploy.ts

@@ -1,5 +1,6 @@
 import { resolve } from "node:path";
 import type { ProjectData } from "@/core/project/types.js";
+import { deployActorsSequentially } from "@/core/resources/actor/deploy.js";
 import { agentResource } from "@/core/resources/agent/index.js";
 import { authConfigResource } from "@/core/resources/auth-config/index.js";
 import {
@@ -20,18 +21,27 @@ import { deploySite } from "@/core/site/index.js";
  * @returns true if there are entities, functions, agents, connectors, or a configured site to deploy
  */
 export function hasResourcesToDeploy(projectData: ProjectData): boolean {
-  const { project, entities, functions, agents, connectors, authConfig } =
-    projectData;
+  const {
+    project,
+    entities,
+    functions,
+    actors,
+    agents,
+    connectors,
+    authConfig,
+  } = projectData;
   const hasSite = Boolean(project.site?.outputDirectory);
   const hasEntities = entities.length > 0;
   const hasFunctions = functions.length > 0;
+  const hasActors = actors.length > 0;
   const hasAgents = agents.length > 0;
   const hasConnectors = connectors.length > 0;
   const hasAuthConfig = authConfig.length > 0;
 
   return (
     hasEntities ||
     hasFunctions ||
+    hasActors ||
     hasAgents ||
     hasConnectors ||
     hasAuthConfig ||
@@ -69,14 +79,22 @@ export async function deployAll(
   projectData: ProjectData,
   options?: DeployAllOptions,
 ): Promise<DeployAllResult> {
-  const { project, entities, functions, agents, connectors, authConfig } =
-    projectData;
+  const {
+    project,
+    entities,
+    functions,
+    actors,
+    agents,
+    connectors,
+    authConfig,
+  } = projectData;
 
   await entityResource.push(entities);
   await deployFunctionsSequentially(functions, {
     onStart: options?.onFunctionStart,
     onResult: options?.onFunctionResult,
   });
+  await deployActorsSequentially(actors);
   await agentResource.push(agents);
   await authConfigResource.push(authConfig);
   const { results: connectorResults } = await pushConnectors(connectors);