devsurface 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 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.
+- Added static repository checks for onboarding documentation, scripts, configuration,
+  environment setup, and declared ports.
+- Added workflow annotations, job summaries, optional update-in-place pull request
+  comments, and configurable failure thresholds.
+- Added safe fallback behavior when fork pull requests have read-only tokens.
+- Added Docker Compose service status with running, stopped, error, and unavailable states.
+- Added dashboard controls to start and stop individual Compose services.
+- Added bounded per-service Docker Compose logs in the Services view.
+- Added Docker Desktop guidance when the engine is not responding on macOS or Windows.
+- Reduced consumer-installed dependencies by bundling the browser opener and keeping
+  React build-only.
+
 ## 0.2.0
 
 - Added retained process logs through `GET /api/logs` so the dashboard can recover session output without relying only on WebSocket state.

package/README.md

@@ -57,7 +57,9 @@ 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.
@@ -109,13 +111,96 @@ 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
+
+DevSurface can check repository onboarding health on every pull request without
+installing dependencies or running project scripts.
+
+```yaml
+name: DevSurface
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  health:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: mrfandu1/devsurface@v0
+        with:
+          fail-on: error
+```
+
+The action always emits workflow annotations and a Markdown job summary. On pull
+requests it also creates or updates one DevSurface comment when the workflow token
+has `pull-requests: write`. Fork pull requests normally receive a read-only token;
+in that case the action keeps the annotations and summary and skips the comment.
+
+Inputs:
+
+| Input          | Default | Description                                                     |
+| -------------- | ------- | --------------------------------------------------------------- |
+| `path`         | `.`     | Repository-relative directory to check.                         |
+| `fail-on`      | `error` | Fail on `error`, `warning`, or never fail with `never`.         |
+| `comment`      | `true`  | Create or update a pull request comment when permissions allow. |
+| `github-token` | token   | Token used only for pull request comments.                      |
+
+The repository checks are intentionally static. They do not install dependencies,
+run package scripts, inspect local ports, require a real `.env`, or contact Docker.
 
 ## What It Detects
 
@@ -126,7 +211,7 @@ Run DevSurface without installing it globally:
 | Scripts         | `package.json` scripts                                             |
 | Environment     | `.env`, `.env.example`, missing and empty keys without values      |
 | Ports           | Configured, inferred, and occupied ports using Node's `net` module |
-| Docker          | Compose files, Docker daemon status, compose service names         |
+| Docker          | Compose files, daemon status, service state, controls, and logs    |
 | Git             | Repository presence and current branch                             |
 | Framework       | Next.js, Vite, Express, Fastify, NestJS, Remix, Prisma             |
 
@@ -141,7 +226,8 @@ The dashboard includes:
 - **Scripts**: every package script, plus grouped configured commands when present.
 - **Environment**: `.env` and `.env.example` status, key presence, and copy-from-example.
 - **Ports**: detected ports with availability and conflict warnings.
-- **Services**: Docker Compose detection and service status.
+- **Services**: Docker Compose daemon state, per-service status, start/stop controls,
+  and the latest 200 log lines for each service.
 - **Logs**: expandable per-command logs with timestamps, streams, and exit state.
 - **Repo Health**: doctor warnings for common setup issues.
 
@@ -199,10 +285,12 @@ 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.
 - Destructive-looking configured commands, such as `rm -rf`, `docker volume rm`,
   database drops, and `git clean -fd`, are visibly marked before execution.
 - Child processes started by DevSurface are cleaned up when the dashboard exits.