devsurface 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.5.0
+
+- Added framework presets for Next.js, Vite, Express, Fastify, NestJS, Remix, and Prisma.
+- Added detected preset commands and ports to the dashboard and command API.
+- Added Python project detection for `requirements.txt`, `pyproject.toml`, and `Pipfile`, including FastAPI/Uvicorn, Flask, and Django commands.
+- Added Go project detection from `go.mod`, with run, build, and test commands.
+- Added Java project detection from Maven and Gradle build files, with build and test commands.
+- Updated doctor checks so detected Python, Go, and Java projects are not treated as broken Node.js projects.
+
+## 0.4.0
+
+- Added multi-workspace Hub mode: one DevSurface instance serves multiple project
+  directories. Run `npx devsurface` in any project to attach it to a running hub.
+- Added `devsurface serve` command for running the hub as a persistent background
+  server, Docker container, or k3s pod.
+- Added `devsurface workspace add|list|remove` commands for managing registered
+  workspaces from the CLI.
+- Added workspace switcher and Hub overview page in the dashboard for comparing
+  projects at a glance.
+- Added workspace-scoped API routes under `/api/workspaces/:id/*` with backward-
+  compatible aliases for single-project setups.
+- Added workspace-scoped WebSocket connections via `?workspace=<id>` query parameter.
+- Added Dockerfile, docker-compose.hub.yml, and deploy/k3s/ Kubernetes manifests
+  for containerized and local-cluster deployments.
+- Added `DEVSURFACE_HOST`, `DEVSURFACE_CONTAINER`, `DEVSURFACE_DATA_DIR`,
+  `DEVSURFACE_WORKSPACES`, and `DEVSURFACE_WORKSPACE_ROOTS` environment variables
+  for container and workspace-root configuration.
+- Kept per-project `devsurface.config.json` unchanged; existing single-project
+  workflows auto-register on first run.
+- Added workspace-root configuration for deployments that should only register
+  projects from mounted directories.
+
 ## 0.3.0
 
 - Added the reusable `mrfandu1/devsurface@v0` GitHub Action.

package/README.md

@@ -6,7 +6,7 @@
 
 <h1>DevSurface</h1>
 
-<p><strong>Turn any Node.js repository into a local developer control panel.</strong></p>
+<p><strong>Local developer dashboard for Node.js repositories.</strong></p>
 
 <p>
   <a href="#quick-start">Quick Start</a>
@@ -22,19 +22,30 @@
   <a href="https://github.com/mrfandu1/devsurface">
     <img alt="DevSurface ready" src="docs/devsurface-badge.svg">
   </a>
+  <a href="https://www.npmjs.com/package/devsurface">
+    <img alt="npm version" src="https://img.shields.io/npm/v/devsurface.svg">
+  </a>
+  <a href="https://www.npmjs.com/package/devsurface">
+    <img alt="npm downloads" src="https://img.shields.io/npm/dm/devsurface.svg">
+  </a>
+  <a href="https://github.com/mrfandu1/devsurface/stargazers">
+    <img alt="GitHub stars" src="https://img.shields.io/github/stars/mrfandu1/devsurface?style=flat">
+  </a>
   <a href="LICENSE">
-    <img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-informational">
+    <img alt="License: MIT" src="https://img.shields.io/github/license/mrfandu1/devsurface">
   </a>
   <img alt="Built with TypeScript" src="https://img.shields.io/badge/Built%20with-TypeScript-3178c6">
 </p>
 
 </div>
 
-DevSurface scans a project, starts a local dashboard, and shows the things contributors
-usually need before a project will run: package scripts, environment files, ports,
-Docker Compose, live command logs, and repo health warnings.
+DevSurface is a zero-config CLI and local browser dashboard for understanding,
+configuring, and running unfamiliar repositories. It detects Node.js package scripts,
+Python, Go, and Java project commands, environment files, occupied ports, Docker
+Compose services, frameworks, live command logs, repo health checks, and
+multi-workspace projects.
 
-No config file is required.
+No global install, account, cloud service, or config file is required.
 
 ```bash
 npx devsurface
@@ -57,11 +68,43 @@ new contributor can see what is missing before guessing in the terminal.
 
 DevSurface is local-first:
 
-- The server binds to `127.0.0.1`.
+- Local runs bind to `127.0.0.1`.
+- Docker and k3s runs bind inside the container and are meant to be exposed with
+  local port mappings or `kubectl port-forward`.
 - No accounts, cloud sync, telemetry, or analytics.
 - `.env` values are never displayed.
 - Commands are shown before they run.
 
+## Use Cases
+
+DevSurface is useful when you need to:
+
+- Onboard contributors to an unfamiliar Node.js repository.
+- Explore available npm, pnpm, Yarn, or Bun scripts.
+- Check missing environment variables before starting a project.
+- Detect local port conflicts.
+- View and control Docker Compose services.
+- Run development commands from a browser dashboard.
+- Check repository onboarding health in GitHub Actions.
+- Manage multiple local project workspaces.
+
+## Supported Frameworks and Tools
+
+DevSurface detects projects using:
+
+- Next.js
+- Vite
+- Express
+- Fastify
+- NestJS
+- Remix
+- Prisma
+- Python: FastAPI/Uvicorn, Flask, Django
+- Go modules
+- Java: Maven and Gradle
+- Docker Compose
+- npm, pnpm, Yarn, and Bun
+
 ## How It Compares
 
 | Tool                   | What it does                                         | Where DevSurface is different                                                                    |
@@ -109,13 +152,52 @@ Run DevSurface without installing it globally:
 | npm     | `npx devsurface`  |
 | Bun     | `bunx devsurface` |
 
-| Command                   | Description                                                          |
-| ------------------------- | -------------------------------------------------------------------- |
-| `devsurface`              | Scan the current project, start the dashboard, and open the browser. |
-| `devsurface scan`         | Print detected project information to the terminal.                  |
-| `devsurface doctor`       | Print setup and repo health warnings.                                |
-| `devsurface init`         | Create a starter `devsurface.config.json`.                           |
-| `devsurface run <script>` | Run a package script and stream output.                              |
+| Command                            | Description                                                          |
+| ---------------------------------- | -------------------------------------------------------------------- |
+| `devsurface`                       | Scan the current project, start the dashboard, and open the browser. |
+| `devsurface scan`                  | Print detected project information to the terminal.                  |
+| `devsurface doctor`                | Print setup and repo health warnings.                                |
+| `devsurface init`                  | Create a starter `devsurface.config.json`.                           |
+| `devsurface run <script>`          | Run a package script and stream output.                              |
+| `devsurface serve`                 | Start the multi-workspace hub server.                                |
+| `devsurface workspace add [path]`  | Register a project directory with the local hub.                     |
+| `devsurface workspace list`        | List registered hub workspaces.                                      |
+| `devsurface workspace remove <id>` | Remove a workspace from the hub registry.                            |
+
+## Multi-Workspace Hub
+
+DevSurface now runs as a local hub. One server can serve several project
+directories, each with isolated process state, Docker controls, logs, and scanner
+results.
+
+Start or attach from any project:
+
+```bash
+npx devsurface
+```
+
+Run a persistent hub:
+
+```bash
+npx devsurface serve --no-open
+```
+
+Register workspaces manually:
+
+```bash
+npx devsurface workspace add /path/to/project-a
+npx devsurface workspace add /path/to/project-b
+npx devsurface workspace list
+```
+
+Container and k3s deployments are included for local-cluster use:
+
+- `Dockerfile`
+- `docker-compose.hub.yml`
+- `deploy/k3s/`
+
+Container deployments bind inside the container. Keep host port mappings local,
+for example `127.0.0.1:4567:4567`, or use `kubectl port-forward` for k3s.
 
 ## GitHub Action
 
@@ -244,8 +326,9 @@ works for the repo:
 
 DevSurface is designed for local development.
 
-- The dashboard server is restricted to `127.0.0.1`.
-- Mutating API routes require dashboard intent headers.
+- Local dashboard servers bind to loopback hosts.
+- Container deployments use `DEVSURFACE_CONTAINER=true`.
+- Workspace registration can be limited with `DEVSURFACE_WORKSPACE_ROOTS`.
 - `.env` values are never returned by scanners, API routes, CLI output, or UI panels.
 - Dashboard command runs show the exact command string first.
 - Docker service start and stop actions show the exact Compose command before running.
@@ -253,6 +336,31 @@ DevSurface is designed for local development.
   database drops, and `git clean -fd`, are visibly marked before execution.
 - Child processes started by DevSurface are cleaned up when the dashboard exits.
 
+## FAQ
+
+### What is DevSurface?
+
+DevSurface is a local developer dashboard for understanding, configuring, and running
+Node.js repositories.
+
+### Can DevSurface run npm scripts from a browser?
+
+Yes. DevSurface detects `package.json` scripts and lets you run them while viewing
+live logs and exit status.
+
+### Does DevSurface display .env values?
+
+No. DevSurface checks whether environment keys exist, but never displays their values.
+
+### Does DevSurface require configuration?
+
+No. It works automatically, with an optional `devsurface.config.json` file for richer
+commands, groups, ports, env paths, and docs links.
+
+### Does DevSurface support Docker Compose?
+
+Yes. It detects Compose services and provides service status, controls, and recent logs.
+
 ## Examples
 
 This repository includes two sample projects: