everything-dev/skills/dev-workflow/SKILL.md

A consolidated product package for building Module Federation apps with oRPC APIs.

---
name: dev-workflow
description: Development workflow for everything-dev projects using bos dev, bos start, and the Module Federation runtime. Use when starting dev servers, debugging hot reload, or understanding the service-descriptor architecture.
metadata:
  sources: "packages/everything-dev/src/service-descriptor.ts,packages/everything-dev/src/orchestrator.ts,packages/everything-dev/src/dev-logs.ts,packages/everything-dev/src/dev-session.ts"
---

# everything-dev Development Workflow

## Starting Development

```bash
# Typical: start development (host mode auto-detected)
bos dev

# Isolate work
bos dev --api remote     # UI only
bos dev --ui remote      # API only
bos dev                  # Full local (rarely needed)
```

## Port Assignments

| Service | Port | URL |
|---------|------|-----|
| host | 3000 | http://localhost:3000 |
| api | 3001 | http://localhost:3001 |
| auth | 3002 | http://localhost:3002 |
| ui | 3003 | http://localhost:3003 |
| ui-ssr | 3004 | http://localhost:3004 |
| plugins | 3010+ | http://localhost:3010+ (incremental — one per plugin in config order) |

## Service-Descriptor Architecture

The orchestrator builds a `ServiceDescriptorMap` from `bos.config.json`. Each descriptor defines:
- `key` — service identifier (host, ui, api, auth, plugin:*)
- `source` — `"local"` or `"remote"` (determines if process is spawned or URL is probed)
- `port` / `defaultPort` — TCP port for local services
- `readinessPath` — HTTP path for readiness probes (e.g., `/health`, `/remoteEntry.js`)
- `readyPatterns` / `errorPatterns` — Regexes matched against stdout/stderr

The orchestrator:
1. Spawns local services via `bun run dev` in each package directory
2. Probes remote services via HTTP GET to their readiness path
3. Tracks process state: pending → starting → ready → error
4. Writes logs to `.bos/logs/{service}.log`

## Hot Reload

- **UI changes**: Rsbuild HMR — instant at :3003, no rebuild
- **API changes**: Rspack HMR — instant at :3001, no rebuild
- **Auth / Plugin changes**: No HMR — require full restart (`bos kill && bos dev`)
- **SSR (ui-ssr)**: No HMR — restart required after UI changes
- **Config changes**: Require host restart (`bos kill && bos dev`)

## Contract Sync & Type Generation

Plugin types are auto-generated from `bos.config.json` via `bos types gen`:

```bash
bos types gen   # Regenerate ui/src/lib/api-types.gen.ts and api/src/lib/plugins-types.gen.ts
```

**When it auto-runs:**
- `bun install` (postinstall hook)
- `bun typecheck`
- `bos dev` startup
- `bos build`, `bos deploy`, `bos publish`
- `bos pluginAdd` / `bos pluginRemove`

**How plugin types are resolved:**
1. `local:plugins/<name>` → reads `src/contract.ts` directly from disk
2. Remote URL → fetches contract types from the deployed plugin's manifest
3. Missing local path with no URL → skipped with a warning

**Source of truth:** `bos.config.json`. If a plugin is listed there, its routes appear on `ApiContract`. If removed, TypeScript catches stale usage.

**After hand-editing `bos.config.json`:** Run `bos types gen` or restart `bos dev` to pick up changes.

## Runtime Config Loading

The host reads `BOS_RUNTIME_CONFIG` at startup (resolved from `bos.config.json` by the CLI). `ConfigService` is an immutable Effect Layer — every service is built from that one snapshot.

**Override for testing**: Set `BOS_RUNTIME_CONFIG` env var to a JSON string or file path to bypass config loading from disk. Useful for testing with different configs without modifying `bos.config.json`.

On page refresh:
1. Browser re-fetches HTML shell from host
2. Host injects current config into `window.__RUNTIME_CONFIG__`
3. Module Federation container re-initializes from fresh `remoteEntry.js`

This means a new deployment requires a host restart to pick up new URLs.

### Resolved Config (`.bos/bos.resolved-config.json`)

`bos dev` and `bos build` write the fully-merged config to `.bos/bos.resolved-config.json` (gitignored). This file includes `_resolved` metadata with env, timestamp, and extends chain.

**`bos.config.json` is NOT modified during dev.** Only `bos publish --deploy`, `bos plugin publish/add/remove`, and `bos sync` write to `bos.config.json`.

Build configs (rsbuild/rspack) read from `.bos/bos.resolved-config.json` first, falling back to `bos.config.json`. This allows slim child configs with `extends` to work correctly — the merged parent+child config is what the build sees.

## Debugging

```bash
bos ps                    # List running processes + ports
bos status                # Check remote health
bos info                  # Show current configuration
ls .bos/logs/             # Available log files
cat .bos/logs/api.log     # API process logs
```

### Port Conflicts

If a port is already in use, the local service fails to start. Check what's on the port:

```bash
lsof -i :3003             # Check what is using port 3003
```

Kill the conflicting process and retry, or stop the existing `bos dev` session first.

### Stale PID file

If `bos kill` doesn't run cleanly (e.g., terminal was closed), stale PIDs in `.bos/pids.json` can block restart:

```bash
rm .bos/pids.json         # Clear stale PID tracking
bos dev                   # Start fresh
```

### API not responding

1. `bos ps` — is API running?
2. `.bos/logs/api.log` — startup errors?
3. `curl http://localhost:3001/remoteEntry.js` — is the entry accessible?

### UI not loading

1. Check browser console for Module Federation errors
2. `bos.config.json` — is `app.ui.development` correct?
3. Clear browser cache and hard reload (Cmd+Shift+R)
4. Verify UI SSR restart if using SSR

### Module Federation errors

- Verify shared dependency versions match across package.json files
- Clear browser cache (Cmd+Shift+R)
- Check `bos.config.json` URLs are accessible

## Production Mode

```bash
bos start --no-interactive                    # All remotes, production URLs
bos start --env staging --no-interactive      # Staging environment
bos start --account foo.near --domain bar.com # Load specific config
```

## Process Management

```bash
bos ps              # Show PID, name, port, started time
bos kill            # Graceful SIGTERM → SIGKILL
bos kill --force    # Immediate SIGKILL
```

Process tracking uses `.bos/pids.json`.