Webstir

Engine

Core implementation that powers the active Bun CLI. In the current monorepo, the engine is the orchestration code under orchestrators/bun/src plus the canonical provider packages under packages/tooling/**.

Overview

  • Parses CLI commands and workspace paths.
  • Chooses the active build plan from the app's layers: pages (src/frontend) and server (src/backend/index.ts).
  • Loads the canonical frontend, backend, and testing packages.
  • Coordinates build, publish, watch, test, and scaffold flows.
  • Keeps the live runtime Bun-first.

Responsibilities

  • Resolve the workspace descriptor from package.json and the app's layers.
  • Run frontend and backend providers in the right order for the app's layers.
  • Serve build/frontend/** in watch mode and proxy /api/* when both surfaces are active.
  • Supervise the frontend watch for apps with pages, plus the backend runtime for apps with a server, in long-running loops.
  • Keep command output compact and machine-friendly enough for CI and smoke flows.

Structure

  • CLI entrypoint: orchestrators/bun/src/cli.ts
  • Command execution: build.ts, publish.ts, watch.ts, test.ts, smoke.ts
  • Workspace and layer resolution: workspace.ts, build-plan.ts, types.ts
  • Provider loading: providers.ts
  • Watch runtime: frontend-watch.ts, api-watch.ts, full-watch.ts
  • Dev server and runtime supervision: dev-server.ts, backend-runtime.ts

Workflow Model

init

  • Copies generated Bun template assets from orchestrators/bun/assets/templates/**
  • Repo contributors edit orchestrators/bun/resources/templates/**, then regenerate assets/** before build or pack boundaries
  • Writes package.json and the starter's src/** layout

build

  • Runs the build plan for the app's layers: frontend for pages, backend for a server
  • Emits readable development artifacts under build/**

publish

  • Reuses the same providers in publish mode
  • Emits optimized frontend assets under dist/frontend/**: the static layout with views rendered at publish when the app has no server, dist/frontend/pages/<page>/ served by the server when it has one
  • Emits backend publish output under build/backend/**

watch

  • Pages only: frontend watch (the build pipeline plus the dev server), rendering build-time views as the publish will
  • Server only: backend watcher + runtime supervisor
  • Pages and server: frontend watch plus backend watcher/runtime and /api/* proxying

test

  • Rebuilds the requested surfaces
  • Compiles discovered src/**/tests/** suites
  • Runs them through the canonical testing provider

Watch Runtime Pieces

  • document-watch.ts: the frontend watch session for every app with pages: rebuilds with the build pipeline and sends each change to the browser as a CSS swap, a page refresh or a reload
  • DevServer: static file server with SSE status/reload events and optional /api/* proxying
  • WorkspaceWatcher: watches src/** and types/**, batching changes and full reload events
  • BackendRuntimeSupervisor: starts build/backend/index.js, waits for readiness, and restarts on successful rebuilds

Provider Boundary

The orchestrator does not implement frontend and backend compilation itself. It delegates to the canonical packages:

  • @webstir-io/webstir-frontend
  • @webstir-io/webstir-backend
  • @webstir-io/webstir-testing

That boundary is the active source of truth for build and runtime behavior.

Outputs

  • Dev: build/frontend/** and/or build/backend/**
  • Publish: dist/frontend/** plus backend publish output in build/backend/**
  • Generated workspace state: .webstir/frontend-manifest.json

Testing

Favor end-to-end command coverage and provider/package tests over internal-unit archaeology. The active test surfaces live in orchestrators/bun/tests/** and the package tests/** directories.