localdeck 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+## 1.0.0 — Product launch
+
+### Project setup and configuration
+
+- Initialize .localdeck from package scripts, preview detection with --dry-run, or define commands explicitly for other languages.
+- Remember projects by configuration-file identity. Show unavailable projects with recovery errors instead of dropping them from the dashboard.
+- Configure startup dependencies, service tags, and named profiles. Start prerequisites first and stop project services in reverse dependency order.
+- Edit project nicknames, public/upstream ports, readiness checks, timing, and dependencies in project settings. Save configuration atomically; apply runtime changes after restart.
+- Disable nickname Save when its normalized value is unchanged. Expand service configuration to the available page width.
+
+### Runtime and networking
+
+- Keep health checks on the detected IPv4 or IPv6 listener, preventing routing to another project using the same port on a different loopback address. Ignore stale health-check results after an upstream change.
+
+- Run existing development commands through a background daemon, with stable public ports and automatic upstream listener detection.
+- Add native Windows process and TCP listener discovery through PowerShell, plus a dedicated Windows networking CI job. Remove built-in Windows/Linux forwarding without invoking the macOS installer.
+- Provide project-qualified service identities and nickname-based localhost URLs. Reject ambiguous bare service names instead of selecting the wrong project.
+- Inject PORT and LOCALDECK_URL and resolve service references for local communication. Support TCP and HTTP readiness checks and database endpoints.
+- Keep terminal-owned and daemon-owned process lifecycles distinct. Clean up child process groups on stop, failed startup, and shutdown.
+- Offer optional port-free URLs through a verified local forwarder, with macOS setup, retry, removal, and fallback to original port URLs.
+- Add a Windows UAC installer for a persistent, loopback-only portproxy rule, guarded by a machine-level ownership marker, with verification and administrator-approved removal. Native elevated testing is pending.
+- Cancel pending public-share startup during shutdown so tunnel startup does not delay service cleanup.
+
+### Dashboard navigation and controls
+
+- Add dedicated /projects, /services, /settings, /about, and /changelog pages with direct links, refresh, and browser Back/Forward support.
+- Render the requested page before daemon data loads, eliminating the All Services flash when refreshing Projects.
+- Search configured and running services across projects. Start and stop services directly in the list; open service output in the Logs panel instead of a separate service page.
+- Add a collapsible, resizable sidebar with saved preferences and a compact mobile layout.
+- Align Local runtime, daemon connection, active-service count, and Logs in one footer row.
+- Show an Enable Clean URLs action above Local runtime when Clean URLs are off. Enable forwarding directly, with pending and retry states.
+- Center action labels and empty states while keeping service rows full-width and left-aligned. Use neutral keyboard focus indicators, underlined Logs controls, and a borderless close icon.
+- Dismiss popup menus on outside interaction or Escape. Remove the redundant project Activity section.
+
+### Logs and troubleshooting
+
+- Start and stop individual services from project pages, open their specific log tabs, and manage sharing with optional passwords, public URL copying, and Stop sharing. Display active public links beneath local service URLs in both service views.
+- Distinguish sharing lifecycle events and tunnel requests with teal SHARE labels; keep application stdout separate.
+- Stream service output live. Select multiple services in a bottom Logs panel, merge their output chronologically, or switch to individual service tabs.
+- Filter retained output, follow new lines, resize the panel with pointer or keyboard, and remember its height.
+- Configure the log-line limit in Settings from 100 to 5,000, with a default of 1,000. Apply it to live buffering and the combined view, and save the preference in the browser.
+- Preserve record identity and ordering when merging history with live output. Retry failed history loads and keep removed sources available for deselection.
+- Explain port conflicts with actionable recovery steps, including Vite strictPort and PORT configuration. Keep raw errors under Technical details and include guidance in startup logs.
+- Record proxied HTTP requests and expose request inspection through the CLI/API. Support bounded GET/HEAD replay through the API.
+- Generate local diagnostics with configuration, readiness failures, and recent logs, redacting environment values and recognized credentials.
+
+### CLI, sharing, and integrations
+
+- Provide init, doctor, commands, up, run, ps, port, logs, requests, stop, open, and daemon-management commands, plus shorthand configured-service launches.
+- Add --h and --v aliases for help and version alongside the standard flags.
+- Share local HTTP services over HTTPS using cloudflared, with optional password protection and explicit share cleanup.
+- Treat incoming public tunnel traffic as reachability confirmation when local DNS probes lag. Add masked share passwords with on-demand reveal and remove input focus outlines.
+- Verify public tunnel connectivity before marking a share active. Keep tunnel startup and failure status in the daemon so refreshing the dashboard preserves it. Close the Share menu on submission and show the allocated URL beside its verification spinner. Show a spinner in the URL position while connecting and an inline error on failure. Suggest opening the pending link after one minute. Bound startup to two minutes and close unreachable tunnels with retry guidance.
+- Forward shared HTTP and WebSocket requests using the upstream Host so Vite accepts tunnel traffic. Preserve the public hostname and HTTPS scheme in forwarded headers.
+- Explain the separate cloudflared installation requirement in Settings, About, and platform-specific sharing errors, with official installation instructions.
+- Expose project and service tools to MCP clients. Access diagnostics through the daemon package export instead of a relative source import.
+- Authenticate CLI control and attach requests with an owner-only daemon token and validate browser origins for dashboard control requests.
+
+### Packaging and release validation
+
+- Prepare one npm package containing the CLI, daemon, and bundled dashboard. Runtime requires Node.js 20 or newer; Bun is used for development and builds.
+- Bundle self-hosted IBM Plex fonts, the LocalDeck icon, license text, and third-party notices.
+- Adopt the LocalDeck Free-Use Proprietary License: free personal and commercial use, with restrictions on selling LocalDeck or charging for access to it.
+- Add TypeScript/Svelte checks, unit and process integration tests, installed-package tests, and clean-build artifact verification.

package/LICENSE

@@ -0,0 +1,49 @@
+LocalDeck Free-Use Proprietary License
+
+Copyright (c) 2026 LocalDeck contributors. All rights reserved.
+
+1. Free use
+
+Permission is granted, free of charge, to download, copy, install, and run
+official, unmodified LocalDeck releases for personal or commercial use.
+You may use LocalDeck to develop, test, and operate your own products and
+services, including products and services that you sell. Your independently
+created code, products, and outputs are not subject to this license merely
+because you used LocalDeck to create or work on them.
+
+2. No resale or paid access
+
+You must not sell, rent, sublicense, or charge for copies of LocalDeck or
+access to LocalDeck, including through a paid bundle, hosted service,
+managed service, or subscription. You may charge for your own products and
+services developed or operated using LocalDeck, provided that you are not
+selling LocalDeck itself or charging customers for access to it.
+
+3. Authorship and notices
+
+You must not claim that you created LocalDeck, present it as your own
+product, or remove or alter its copyright, license, or authorship notices.
+Using LocalDeck does not require adding LocalDeck branding or attribution
+to your own independently created products.
+
+4. Reserved rights
+
+Except as expressly permitted above or required by applicable law,
+modification, redistribution, and creation of derivative works of LocalDeck
+require prior written permission from the copyright holders. Public
+availability of the source code does not grant additional rights.
+
+5. Third-party components
+
+Third-party components remain subject to their respective licenses, listed
+in THIRD_PARTY_NOTICES.md in the distributed package. This license does not
+restrict rights granted by those third-party licenses.
+
+6. Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,153 @@
+# LocalDeck
+
+**One place to run, inspect, and share your local development services.**
+
+LocalDeck runs the commands your project already uses, gives web services stable local addresses, and brings their controls and logs into a browser dashboard. Use it for a single app or a monorepo with frontends, APIs, and database dependencies.
+
+## Install
+
+Requires **Node.js 20 or newer**. The npm package includes the CLI, background daemon, and dashboard; Bun is only needed to develop LocalDeck.
+
+```sh
+npm install -g localdeck
+localdeck --version
+```
+
+## Quick start
+
+In your application's directory:
+
+```sh
+localdeck init --dry-run   # Preview services detected from package.json
+localdeck init             # Save the .localdeck configuration
+localdeck doctor           # Check configuration and required tools
+localdeck up               # Start the project and its dependencies
+```
+
+In another terminal:
+
+```sh
+localdeck open             # Open the dashboard
+```
+
+The dashboard is served at `http://localhost:7777` by default. It remembers projects registered through the CLI. You can start and stop individual services, open local and shared links, and follow selected services in a resizable logs panel.
+
+`localdeck up` runs in the foreground: **Ctrl-C stops the services it owns**. Services started from the dashboard continue in the background until you stop them or shut down the daemon.
+
+## What you get
+
+- **Stable addresses:** keep a consistent local port even when the development server chooses another upstream port.
+- **Project controls:** start one service or a whole project, with dependencies started in order and checked for readiness.
+- **Clean URLs:** optional addresses such as `http://platform.web.localhost`, with a project nickname and port-80 forwarding enabled.
+- **Combined logs:** select multiple services, switch between their tabs, filter output, and choose a display limit from 100 to 5,000 lines.
+- **HTTPS sharing:** create temporary Cloudflare links with optional password protection, pending status, and shared-request logs.
+- **Coding-agent access:** an MCP server for service inspection, controls, diagnostics data, and recorded GET/HEAD replay.
+
+## Configure your services
+
+Create a `.localdeck` file in your project root, or edit the one generated by `init`:
+
+```json
+{
+  "nickname": "platform",
+  "services": [
+    { "name": "api", "run": "npm run dev:api", "ready": "/health" },
+    { "name": "web", "run": "npm run dev:web", "after": "api" }
+  ]
+}
+```
+
+Replace the commands and health endpoint with your project's values. `after` starts the API before the web service and waits for readiness. Omit `ready` to use the default TCP check.
+
+For a non-JavaScript service:
+
+```sh
+localdeck init --name web --command 'python3 -m http.server {port}'
+```
+
+LocalDeck supplies `PORT` and expands `{port}` to the application's upstream port. It can also detect listening ports on macOS, Linux, and Windows. Configure `upstream` explicitly when detection is unavailable. The optional `port` field is the stable proxy port, not the port your development server should bind.
+
+See [configuration](https://github.com/AdstraliaDev1/local-deck/blob/main/docs/configuration.md) for working directories, profiles, environment references, database services, and advanced readiness checks.
+
+## Everyday commands
+
+| Command | Purpose |
+| --- | --- |
+| `localdeck web` | Start the configured web service and its prerequisites. |
+| `localdeck up --profile app` | Start a saved group of services. |
+| `localdeck ps` | List service states, ports, and URLs. |
+| `localdeck logs web -f` | Follow a service's output. |
+| `localdeck requests web` | Inspect recent proxied requests. |
+| `localdeck open web` | Open the local service URL. |
+| `localdeck stop web` | Stop a service and its share. |
+| `localdeck share web` | Create a share with a generated password. |
+| `localdeck unshare web` | Close the share while keeping the service running. |
+| `localdeck --h` / `localdeck --v` | Show help / version. |
+
+When projects have the same service name, use `project/service` or the exact key shown by `localdeck ps`. See the [full command reference](https://github.com/AdstraliaDev1/local-deck/blob/main/docs/commands.md).
+
+## Share over HTTPS
+
+Sharing requires **cloudflared**, installed separately and available on `PATH`. Local services and Clean URLs do not require it. Follow [Cloudflare's installation instructions](https://developers.cloudflare.com/tunnel/downloads/), then check:
+
+```sh
+cloudflared --version
+localdeck share web
+```
+
+The CLI generates a password by default. Use `--password <password>` to choose one, or `--public` for an unprotected link. In the dashboard, choose **Share**, enter an optional password, and submit. A blank dashboard password creates an unprotected share.
+
+The generated URL appears beside a spinner while LocalDeck checks connectivity. After one minute, the dashboard suggests opening the link yourself; a request reaching the public tunnel also confirms connectivity. Startup ends after two minutes if the link still cannot be verified. Pending and failed states survive a dashboard refresh. Protected links have a masked password with **Show/Hide**.
+
+Quick Tunnel URLs are temporary and may have DNS delays. They stop when the service or daemon stops, and recreating a share changes its address. Cloudflare does not guarantee Quick Tunnel uptime. Named tunnels and custom public domains are not configured by LocalDeck v1.
+
+## Clean URLs and networking
+
+Enable **Clean URLs** in Settings, or use the prompt above the dashboard footer. LocalDeck verifies forwarding before removing the port from links. Setup may request administrator approval on macOS or Windows. If forwarding is unavailable, the original port-number URLs remain usable.
+
+CORS still belongs to your application. `http://localhost:3001`, `http://platform.web.localhost`, and a public HTTPS tunnel URL are different browser origins. Add the frontend origin you actually visit to your API's allowlist. LocalDeck does not rewrite CORS policies or application API URLs.
+
+Windows process discovery and an administrator forwarder are implemented. Windows UAC installation, removal, and reboot persistence still need manual validation on Windows; see [platform details](https://github.com/AdstraliaDev1/local-deck/blob/main/docs/dashboard.md#windows).
+
+## Connect a coding agent
+
+Add LocalDeck to an MCP client's server configuration:
+
+```json
+{
+  "mcpServers": {
+    "localdeck": {
+      "command": "localdeck",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Use `localdeck mcp --project <id>` to restrict access to one remembered project. See [MCP setup and tools](https://github.com/AdstraliaDev1/local-deck/blob/main/docs/mcp.md).
+
+## Troubleshooting
+
+- **Port already in use:** check `localdeck ps` and the service logs. LocalDeck does not terminate unrelated processes. For a strict-port development server, use its assigned `PORT` or configure the correct `upstream`.
+- **Sharing fails:** check `cloudflared --version`, network connectivity, and the sharing error. A local app can work while Cloudflare DNS is unavailable.
+- **Changes or upgrades do not take effect:** the daemon keeps the code it loaded at startup. Restart it, then start your services again:
+
+  ```sh
+  localdeck daemon stop
+  localdeck daemon start
+  ```
+
+  Stopping the daemon ends its running services and shares.
+
+## Documentation
+
+- [Configuration](https://github.com/AdstraliaDev1/local-deck/blob/main/docs/configuration.md)
+- [CLI reference](https://github.com/AdstraliaDev1/local-deck/blob/main/docs/commands.md)
+- [Dashboard and platform support](https://github.com/AdstraliaDev1/local-deck/blob/main/docs/dashboard.md)
+- [MCP integration](https://github.com/AdstraliaDev1/local-deck/blob/main/docs/mcp.md)
+- [Development](https://github.com/AdstraliaDev1/local-deck/blob/main/docs/development.md) and [architecture](https://github.com/AdstraliaDev1/local-deck/blob/main/docs/architecture.md)
+- [Changelog](https://github.com/AdstraliaDev1/local-deck/blob/main/CHANGELOG.md) and [release instructions](https://github.com/AdstraliaDev1/local-deck/blob/main/docs/releasing.md)
+
+## License
+
+Free for personal and commercial use, including building and selling your own products. You may not sell LocalDeck, charge for access to it, or claim it as your own product. Modification and redistribution require permission under the [custom proprietary license](https://github.com/AdstraliaDev1/local-deck/blob/main/LICENSE). Bundled dependencies retain their own licenses; the package includes `THIRD_PARTY_NOTICES.md`.