portcall 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joris Gallot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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
+AUTHORS OR 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

@@ -1,3 +1,82 @@
-# Temporary Holding Version
+# portcall
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Run your local dev servers in the background, on fixed ports, with logs your coding agents can read.
+
+When several apps run at once, dev servers pile up: ports to keep apart, terminals to keep open, and coding agents that start a second `pnpm dev`, forget the one they started, or can't see the backend error behind a failing request. portcall gives each project a `portcall.json`, runs its servers detached, and answers the questions an agent (or you) keeps asking:
+
+```sh
+portcall status                 # what runs, on which port
+portcall up                     # start what is not running, wait for the ports
+portcall logs server --errors   # the error behind that 500, with its stack trace
+portcall restart web
+portcall ports                  # every project's ports, and conflicts between them
+```
+
+## Install
+
+```sh
+npm i -g portcall
+```
+
+Node 20.19+, macOS or Linux.
+
+## Configure
+
+`portcall.json` at the project root:
+
+```json
+{
+  "$schema": "https://unpkg.com/portcall/schema.json",
+  "name": "myapp",
+  "services": {
+    "server": { "command": "pnpm dev:server", "port": 3000 },
+    "web": {
+      "command": "pnpm dev:web",
+      "port": 5173,
+      "env": { "VITE_API_URL": "http://localhost:{ports.server}" }
+    },
+    "db": { "port": 5432 }
+  }
+}
+```
+
+- Each command runs with `PORT` set to its service's port. `env` takes `{port}` and `{ports.<service>}`.
+- A service without `command` is external (a database in Docker, a tunnel...): portcall only checks that its port answers.
+- `cwd` runs a command in a subfolder; `readyTimeout` (seconds, default 60) bounds how long `up` waits for the port.
+
+## Commands
+
+| Command | |
+| --- | --- |
+| `portcall up [service...]` | Start services and wait for their port. A no-op for services already running; prints the log tail when one crashes. |
+| `portcall down [service...]` | Stop services (the whole process group, so `pnpm dev` takes its children with it). |
+| `portcall restart [service...]` | Stop, then start. |
+| `portcall status [--all]` | State, port, pid and uptime of each service; `--all` for every known project. |
+| `portcall logs [service...]` | `-n 200`, `--since 5m`, `--grep <regex>`, `--errors`, `-f`. |
+| `portcall ports` | Every known project's ports, with conflicts. Exits 1 on a conflict. |
+| `portcall agents` | Prints a section to paste into `AGENTS.md` / `CLAUDE.md`. |
+
+Every command takes `--json`, `-p <project>` (act on a known project from anywhere) and `-C <dir>`.
+
+### Service states
+
+| State | Meaning |
+| --- | --- |
+| `running` / `starting` | portcall runs it; its port answers / doesn't yet |
+| `crashed` | portcall ran it and it exited on its own (`status` shows the exit code, `logs` why) |
+| `stopped` | nothing on its port |
+| `unmanaged` | its port is held by a process started inside the project, outside portcall (say, in a terminal). `up` leaves it be; `down --force` stops it |
+| `taken` | its port is held by something outside the project. portcall never touches it |
+| `elsewhere` | portcall runs it from another checkout of the project (a git worktree) |
+
+## With coding agents
+
+Run `portcall agents` and paste the result into the project's agent instructions. Agents then check `portcall status` instead of guessing, start servers with `portcall up` (which never starts a second copy), and read `portcall logs --errors` after a failing request instead of asking you to copy the terminal.
+
+## How it works
+
+`portcall up` starts one small detached supervisor per service. It runs the command in its own process group, writes its output, timestamped and without escape codes, to `~/.portcall/logs/<project>/<service>.log` (the previous run is kept as `.log.1`), and records how the service ended. State lives in `~/.portcall` (`PORTCALL_HOME` to move it). Servers keep running when the terminal or agent session that started them ends.
+
+## License
+
+MIT