devsurface 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 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.
+- Added dashboard keyboard shortcuts for refresh, section navigation, settings, sidebar collapse, and drawer close.
+- Added exit-code-aware process status labels in the dashboard.
+- Kept dashboard settings in memory to avoid browser storage.
+- Documented `bunx devsurface` as a no-install launch command.
+
 ## 0.1.0
 
 - Initial DevSurface MVP scaffold.

package/README.md

@@ -1,8 +1,34 @@
-# DevSurface
+<!-- markdownlint-disable MD033 MD041 -->
 
-[![DevSurface ready](docs/devsurface-badge.svg)](https://github.com/mrfandu1/devsurface)
+<a id="readme-top"></a>
 
-Turn any Node.js repository into a local developer control panel.
+<div align="center">
+
+<h1>DevSurface</h1>
+
+<p><strong>Turn any Node.js repository into a local developer control panel.</strong></p>
+
+<p>
+  <a href="#quick-start">Quick Start</a>
+  &nbsp;&middot;&nbsp;
+  <a href="#commands">Commands</a>
+  &nbsp;&middot;&nbsp;
+  <a href="#dashboard">Dashboard</a>
+  &nbsp;&middot;&nbsp;
+  <a href="https://github.com/mrfandu1/devsurface/issues">Report an issue</a>
+</p>
+
+<p>
+  <a href="https://github.com/mrfandu1/devsurface">
+    <img alt="DevSurface ready" src="docs/devsurface-badge.svg">
+  </a>
+  <a href="LICENSE">
+    <img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-informational">
+  </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,
@@ -14,6 +40,12 @@ No config file is required.
 npx devsurface
 ```
 
+With Bun:
+
+```bash
+bunx devsurface
+```
+
 ![DevSurface demo](docs/devsurface-demo.gif)
 
 ## Why DevSurface
@@ -52,6 +84,13 @@ cd my-node-project
 npx devsurface
 ```
 
+Or, if you use Bun:
+
+```bash
+cd my-node-project
+bunx devsurface
+```
+
 The dashboard opens at:
 
 ```text
@@ -63,6 +102,13 @@ terminal.
 
 ## Commands
 
+Run DevSurface without installing it globally:
+
+| Runtime | Command           |
+| ------- | ----------------- |
+| npm     | `npx devsurface`  |
+| Bun     | `bunx devsurface` |
+
 | Command                   | Description                                                          |
 | ------------------------- | -------------------------------------------------------------------- |
 | `devsurface`              | Scan the current project, start the dashboard, and open the browser. |
@@ -71,6 +117,50 @@ terminal.
 | `devsurface init`         | Create a starter `devsurface.config.json`.                           |
 | `devsurface run <script>` | Run a package script and stream output.                              |
 
+## 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
 
 | Area            | Detection                                                          |
@@ -80,7 +170,7 @@ terminal.
 | 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             |
 
@@ -95,7 +185,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.
 
@@ -157,6 +248,7 @@ DevSurface is designed for local development.
 - Mutating API routes require dashboard intent headers.
 - `.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.
@@ -205,18 +297,21 @@ npm test
 npm run build
 ```
 
-## Publishing
+## Contributing
+
+Contributions of every kind are welcome: code, documentation, bug reports,
+examples, and reviews. Start with [CONTRIBUTING.md](CONTRIBUTING.md) for the
+development workflow.
 
-The npm package is allowlisted through `package.json#files`. The package includes the
-built CLI, built web UI, README, demo GIF, license, and changelog. Private notes,
-tests, examples, and development-only files are excluded from npm publishes.
+## License
 
-Check package contents before publishing:
+DevSurface is released under the MIT License. See [LICENSE](LICENSE) for the full
+text. Copyright (c) 2026 DevSurface contributors.
 
-```bash
-npm pack --dry-run
-```
+## Contact and community
 
-## License
+- GitHub Issues: report bugs and request features through
+  [GitHub Issues](https://github.com/mrfandu1/devsurface/issues).
+- Security: report vulnerabilities through [SECURITY.md](SECURITY.md).
 
-MIT. See [LICENSE](LICENSE).
+[(back to top)](#readme-top)

package/SECURITY.md

@@ -0,0 +1,9 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+Please report security issues privately by opening a GitHub security advisory or by
+emailing the maintainer listed in the repository profile.
+
+DevSurface runs local commands from the project it scans. It never binds outside
+`127.0.0.1`, never sends telemetry, and never exposes `.env` values.