refactor(dev): decouple the serveCommand lifecycle from the dev server

[davidsu]

Note

Description

Moves ownership of the frontend site.serveCommand process out of the dev server and into the base44 dev command. createDevServer() is now purely the backend: it no longer takes an appId, no longer spawns or supervises the frontend process, and instead exposes a shutdown() handle. The command layer decides whether a serve command is configured, starts it, and wires signal handling and teardown around it. Pure refactor — the observable behavior of base44 dev is unchanged.

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

• Added packages/cli/src/cli/dev/serve-command-runner.ts with createServeCommandRunner(), which builds a ServeRunner configured with the project root as cwd, the VITE_BASE44_APP_ID / VITE_BASE44_APP_BASE_URL env vars, and the orange frontend dev logger.
• createDevServer() (dev-server/main.ts): dropped the appId option and all ServeRunner construction, startup, exit-handling and teardown; replaced the isServingFrontend result field with shutdown: () => Promise<void> so callers can tear the backend down themselves.
• commands/dev.ts: extracted requireLinkedProject(), createConfiguredServeRunner() and startServeCommand() helpers out of devAction(); the command now reads site.serveCommand, starts the runner, registers SIGINT/SIGTERM handlers, and exits the process after shutting the backend down if the frontend dies.
• The outro message now keys off whether a runner was created rather than the removed isServingFrontend flag; the "Backend running on …" line is emitted by the command via a backend dev logger.

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

Existing coverage in `packages/cli/tests/cli/dev.spec.ts` already exercises both paths this refactor touches — running the frontend `serveCommand` with injected Base44 env vars, and stopping it when the dev server stops — and no test changes were needed. The tests were not executed as part of generating this description.

One consequence worth noting: `readProjectConfig()` is now called a second time inside `createConfiguredServeRunner()` (the dev server's `loadResources` already reads it), so the project config is parsed twice on startup.

---

_{🤖 Generated by Claude | 2026-07-30 12:30 UTC | 27b0175}

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/cli@0.1.6-pr.582.27b0175

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.582.27b0175"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "base44": "npm:@base44-preview/cli@0.1.6-pr.582.27b0175"
  }
}

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

---

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