# RFC: Auto-detect & launch dev server for folder-imported projects

**Status:** Draft (for nexu-io/open-design Issue, post #597 merge)
**Author:** @infinity-nft
**Related:** #597 (folder import — single mode)

## Summary

When a user imports an existing local folder as a project (#597), the
folder is often a real frontend project (Next.js / Vite / CRA / Astro /
plain `npm run dev`). Currently OD opens such projects as a static file
panel — the user has to launch the dev server themselves in another
terminal and then iframe-load it manually.

This RFC proposes letting OD detect a dev-server config from the
imported folder's `package.json` and offer to launch it inline, so the
preview pane shows the live app instead of static HTML.

## Problem

After landing #597, the user picks `~/projects/marketing-site/` (a
Next.js app). What they see in OD's preview pane:

- File panel with `next.config.js`, `pages/index.tsx`, etc.
- No way to render the app — it needs `next dev` running on port 3000.

What they want:

- Click "Open folder" → OD detects `next dev` script → asks "Launch
  dev server?" → preview pane shows the live app at localhost:3000
  inside the iframe.

This is the bridge that makes folder-import useful for real workflows
(generating components, iterating on UI), not just static HTML.

## Proposed behavior

### Detection (no new endpoint, runs at import time)

The import endpoint scans `<baseDir>/package.json` (and a few common
subdirs: `frontend/`, `client/`, `web/`, `app/`, `packages/web/`) for
a runnable script:

1. `pkg.scripts.dev` if present, else `pkg.scripts.start`
2. Extract a port from `--port N` / `-p N` flags in the script string
3. Fall back to framework defaults: `next` → 3000, `vite` → 5173,
   `react-scripts` → 3000, `astro` → 4321
4. Detect package manager from lockfiles (`pnpm-lock.yaml` → pnpm,
   `yarn.lock` → yarn, default → npm)

If detected, stamp `metadata.devServer = { script, cwd, port }` on the
project at import time. Otherwise no devServer field — project behaves
exactly as a static file panel.

### Launching (lifecycle endpoints)

- `POST /api/projects/:id/dev-server/start` — spawn the configured
  script via `pkg-manager run dev-script` in `<baseDir>/<cwd>`. Track
  the child process in an in-memory map keyed by project id.
- `POST /api/projects/:id/dev-server/stop` — kill the tracked child.
- Daemon `process.on('exit')` / SIGINT / SIGTERM kills all running
  dev servers on shutdown.

The endpoint waits for the configured port to respond (with a 30 s
timeout) before resolving, so the UI can show a clear "starting…" /
"ready" / "failed" state.

### UI

- New project section / Project view: when `metadata.devServer` is
  set, render the preview pane as an iframe pointed at
  `http://localhost:${devServer.port}` (auto-started on project open).
- Toolbar gets `Stop` / `Start` symmetric controls (when stopped, file
  panel + a banner with Start button; when running, iframe + Stop).
- No devServer config detected → behaves like today (file panel only).

## Open questions

1. **Permission model** — running `npm install` + `npm run dev` on a
   user folder is more privileged than reading files. Should OD prompt
   on first launch ("This folder will run `pnpm dev` — proceed?") with
   per-project consent, similar to VS Code's "trust" prompt?
2. **Auto-install missing dependencies** — if `node_modules` is missing,
   should OD offer to run `pnpm install` first? Or fail clearly and let
   the user run it themselves?
3. **Port conflicts** — if 3000 is taken, should OD pick the next free
   port, or refuse and surface the conflict? Vite has its own
   auto-increment; matching that would be least surprising.
4. **Resource cleanup on project close** — kill the dev server when the
   user navigates away, or keep it running until daemon shutdown? VS
   Code keeps tasks alive; closing == background. Mirroring that feels
   right.
5. **Subprocess output streaming** — should the daemon stream the dev
   server's stdout/stderr to the UI (so users see Next/Vite errors
   inline) or just spawn detached?
6. **Non-folder projects** — current OD can generate project-owned files
   outside imported folders. This RFC MUST NOT define daemon data paths;
   read the root `AGENTS.md` section **Daemon data directory contract**
   before changing or documenting project storage. Should those projects also
   get a "launch dev server" affordance if they happen to have a
   `package.json`? Or is this strictly a folder-import feature?

## Implementation notes (from working prototype)

I have this implemented in my fork — same single-mode philosophy as
#597 (no two paths, no opinions about git). Detection logic is ~30
lines, lifecycle endpoints + child-process registry ~80 lines, UI
wiring ~100 lines. Happy to adapt to whichever direction the design
discussion lands.

## Out of scope

- HMR support (dev servers handle their own HMR; OD just iframes)
- Production builds (`pnpm build` is the user's concern)
- Custom proxy / rewrites between OD daemon and dev server
- Authenticated dev servers (e.g. behind a login)