feat(cli): install and serve a site through the CLI

[ronnyrin]

Note

Description

Adds the two commands a hosted build sandbox needs to bring a project up without a developer at the keyboard: base44 install (run the site's installCommand and nothing else) and base44 site dev (run the site's dev server with no local backend, the frontend reaching its backend same-origin). base44 build is also relaxed to requireAuth: false, since it resolves the app id locally and runs a local build. All three are local-only paths, so a machine that has never logged in can install, build and serve a checkout.

site dev takes no arguments at all: the bind address and the dev server's spelling of its bind-address flag come from new site.devHost / site.devPort / site.devHostFlag config keys, which default to 0.0.0.0, 5173 and --host. A serveCommand that cannot receive forwarded arguments is refused rather than silently served on a different address.

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 base44 install (src/cli/commands/project/install.ts): runs the site block's installCommand via runTask, registered in program.ts. requireAuth: false and requireAppContext: false — no app to resolve, no API call. Fails with an actionable hint when the project has no site block.
• New base44 site dev (src/cli/commands/site/dev.ts): reads the project config, falls back to npm run dev when the site block names no serveCommand, appends the configured bind address, and runs it through the existing ServeCommandRunner. requireAuth: false; exits with the child's code and tears down on SIGINT/SIGTERM.
• New withServeAddress() core helper (src/core/site/serve-command.ts): appends <hostFlag> <host> --port <port> to npm run <script> (through --) and to pnpm/yarn/bun run scripts (directly), plus npm --prefix <path> run <script>. Script and prefix tokens are matched as narrow charsets rather than \S+, so shapes like npm run dev;evil or npm run $(id) are not treated as forwarding shapes. Returns droppedAddress alongside the command so "no address to append" cannot be confused with "the address went nowhere"; site dev turns a dropped address into a hard failure instead of a warning plus exit 0.
• Config schema (src/core/project/schema.ts): site.devHostFlag (default --host; --hostname for Next, which exits on --host), site.devHost (default 0.0.0.0) and site.devPort (default 5173, validated 1–65535). serveCommand and outputDirectory still deliberately do not default — their absence is the signal base44 dev and deploy read.
• base44 build no longer requires auth (src/cli/commands/project/build.ts): requireAuth: false, since the app id comes from --app-id, BASE44_APP_ID or .app.jsonc and the build is local.
• appBaseUrl is now optional on ServeCommandRunnerOptions: when omitted, VITE_BASE44_APP_BASE_URL is not injected, so a same-origin frontend (the Base44 vite plugin proxies /api) is not pointed across origins. base44 dev still passes it.
• Extracted stopRunnerOnProcessSignals() out of commands/dev.ts into src/cli/dev/stop-runner-on-signals.ts so both dev and site dev share it.
• CHANGELOG updated with entries for all of the above.

Testing

• I have tested these changes locally
• I have added/updated tests as needed
• All tests pass (npm test)

New/updated test coverage:

• tests/core/serve-command.spec.ts — cases over withServeAddress: npm via --, pnpm/yarn/bun direct, custom host flag, --prefix scripts, trimming, the fallback command, plus table-driven cases for non-forwarding shapes (vite, next dev, chained commands, already-pinned ports) and for injection-shaped strings.
• tests/cli/site_dev.spec.ts — default sandbox address, config-supplied address, rejection of --port, refusal of a non-forwarding serveCommand, serving without a login, the --hostname spelling, same-origin env (URL=undefined), and the no-site-block failure. Driven by runLive against serve.js fixtures that echo their argv and env.
• tests/cli/install.spec.ts — configured installCommand runs, works without a login, surfaces a failing command, fails without a site block.
• tests/cli/build.spec.ts — builds without a logged-in user.
• tests/core/project.spec.ts — the three new schema defaults.
• New fixtures: with-dev-address, with-hostname-serve-command, with-npm-serve-command, with-installable-site, with-failing-install.

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

Division of labour between the three dev paths: base44 dev is the developer machine (local backend), base44 dev --remote is the developer machine against the published backend, and base44 site dev is the hosted-sandbox path (frontend only, same-origin backend). base44 dev is unaffected by the new config keys — it binds nothing.

The commit history walks through several designs for where the bind address lives (command flags, then --backend-url, then config); the final shape is config-only, so base44 site dev needs no arguments and no caller has to know the values.

docs/ topic guides were not touched — the new commands follow the existing factory / Base44Command pattern rather than changing it — but the new site.dev* config keys may be worth a mention in the project-structure docs.

---

_{🤖 Generated by Claude | 2026-09-23 13:04 UTC | c3a4ce4}

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/cli@0.1.18-pr.635.c3a4ce4

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.18-pr.635.c3a4ce4"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "base44": "npm:@base44-preview/cli@0.1.18-pr.635.c3a4ce4"
  }
}

• 📦 Preview Package: @base44-preview/cli@0.1.18-pr.635.c3a4ce4
• 🔗 View this commit on GitHub

---

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