portzilla 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -21,7 +21,7 @@
21
21
  - **Ask before you kill** — `portzilla who 3000` tells you who owns a port. JSON everywhere so agents can consume it directly.
22
22
  - **Guard by default** — intercepts `kill`, `lsof | xargs kill`, `fuser -k`, `kill-port` and blocks kills against another session's live lease.
23
23
 
24
- Existing tools (`witr`, `kill-port`, ServerSlayer) tell you what's on a port *after* the fact. `portzilla` prevents the conflict in the first place.
24
+ Port allocators and proxies such as [Portless](https://portless.sh) solve addressability and automatic port selection. `portzilla` focuses on a different boundary: declaring which agent session owns a process and preventing another agent from killing it. It stays daemon-less by default, requires no local proxy or CA, and works with any server command that consumes the assigned port.
25
25
 
26
26
  ![Portzilla preventing a port conflict](docs/assets/portzilla-demo.gif)
27
27
 
@@ -31,6 +31,7 @@ Existing tools (`witr`, `kill-port`, ServerSlayer) tell you what's on a port *af
31
31
  - [Demo](#demo)
32
32
  - [Install](#install)
33
33
  - [Commands](#commands)
34
+ - [Agent skill](#agent-skill)
34
35
  - [Watch mode](#watch-mode)
35
36
  - [MCP server](#mcp-server)
36
37
  - [Kill guard](#kill-guard)
@@ -56,6 +57,15 @@ PORT PID STATUS AGE TAG
56
57
 
57
58
  Data-producing commands accept `--json` for agent consumption. See [CLI reference](docs/CLI.md).
58
59
 
60
+ Prefer `run` when starting a server — it claims the port and holds the lease for the real server process:
61
+
62
+ ```console
63
+ $ portzilla run 3000 --tag "vite dev" -- sh -c 'npm run dev -- --port "$PORTZILLA_PORT"'
64
+ running on port 3000
65
+ ```
66
+
67
+ The exact child command is framework-specific: whatever starts your server must read the assigned port from `$PORTZILLA_PORT`. On conflict `run` reassigns to the next free port and reports it on stderr; the server child's stdout stays untouched.
68
+
59
69
  ## Demo
60
70
 
61
71
  ```console
@@ -94,7 +104,7 @@ $ cargo install --path .
94
104
  ```console
95
105
  $ curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/011010/portzilla/main/scripts/install.sh | sh
96
106
  # specific version / directory:
97
- $ curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/011010/portzilla/main/scripts/install.sh | PORTZILLA_VERSION=0.2.0 PORTZILLA_INSTALL_DIR=/usr/local/bin sh
107
+ $ curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/011010/portzilla/main/scripts/install.sh | PORTZILLA_VERSION=0.3.0 PORTZILLA_INSTALL_DIR=/usr/local/bin sh
98
108
  ```
99
109
 
100
110
  **npm** (same native binary):
@@ -113,10 +123,22 @@ Binaries for Linux x86_64/ARM64, macOS Intel/Apple Silicon, Windows x86_64/ARM64
113
123
  | `portzilla who <PORT>` | Show lease on a port (exit `2` if none) |
114
124
  | `portzilla release <PORT>` | Remove lease (always wins; warns if PID still alive) |
115
125
  | `portzilla prune` | Remove all leases whose PID is dead |
126
+ | `portzilla run <PORT> --tag <TAG> [--session <S>] -- <cmd...>` | Claim a port and run a server with it; the lease follows the child PID |
116
127
  | `portzilla watch [--interval <SECONDS>]` | Repeatedly prune leases whose recorded PID is dead |
117
128
 
118
129
  Data-producing commands are file-locked and support `--json`. Full flags, conflict semantics, exit codes and JSON shapes → **[docs/CLI.md](docs/CLI.md)**.
119
130
 
131
+ ## Agent skill
132
+
133
+ For OpenCode agents, install the checked-in `portzilla` skill explicitly:
134
+
135
+ ```console
136
+ $ mkdir -p .opencode/skills/portzilla
137
+ $ portzilla init skill > .opencode/skills/portzilla/SKILL.md
138
+ ```
139
+
140
+ `init skill` only prints the skill file to stdout — it never writes configuration for you; the redirect above is what saves it. The skill teaches the agent to start servers with `portzilla run` and `$PORTZILLA_PORT`. Kill-guard setup stays separate: `portzilla init opencode` prints the `portzilla.js` plugin shim (see [Kill guard](#kill-guard)).
141
+
120
142
  ## Watch mode
121
143
 
122
144
  `portzilla watch` is an optional foreground watcher. It is not a central IPC
@@ -203,11 +225,11 @@ Resolution order: `PORTZILLA_DATA_DIR` → `$XDG_DATA_HOME/portzilla` → `~/.lo
203
225
 
204
226
  **State-file versions.** New writes use a versioned `leases.json` envelope (`format_version: 2`) so newer identity fields cannot be silently discarded. Legacy bare-array files are read and upgraded on the next write. Older binaries cannot safely read v2 files and must be upgraded before using the same data directory; unknown future versions are rejected without rewriting the file.
205
227
 
206
- `portzilla` does not start/stop servers, enforce firewall/sandbox, or coordinate across machines.
228
+ `portzilla run` starts one server command and waits for it, but Portzilla does not stop, restart, or supervise arbitrary servers. It does not enforce a firewall/sandbox or coordinate across machines.
207
229
 
208
230
  ## Roadmap
209
231
 
210
- v0.1: `claim`/`ls`/`who`/`release`/`prune` + JSON + locked state. v0.1.x: MCP server. v0.2: kill guard + harness adapters + `portzilla guard`. The optional foreground `watch` command is implemented; an active daemon remains future work. Full plan → [`docs/ROADMAP.md`](docs/ROADMAP.md). Release procedure → [`docs/RELEASING.md`](docs/RELEASING.md).
232
+ v0.1: `claim`/`ls`/`who`/`release`/`prune` + JSON + locked state. v0.1.x: MCP server. v0.2: kill guard + harness adapters + `portzilla guard`. v0.3: `portzilla run` + installable agent skill. The optional foreground `watch` command is implemented; an active daemon remains future work. Full plan → [`docs/ROADMAP.md`](docs/ROADMAP.md). Release procedure → [`docs/RELEASING.md`](docs/RELEASING.md).
211
233
 
212
234
  ## License
213
235
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "portzilla",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "description": "Port and process lease coordinator for parallel AI coding-agent sessions",
5
5
  "license": "MIT",
6
6
  "homepage": "https://github.com/011010/portzilla",
@@ -20,6 +20,7 @@
20
20
  "files": [
21
21
  "npm/bin.js",
22
22
  "npm/install.js",
23
+ "skills/portzilla/SKILL.md",
23
24
  "README.md",
24
25
  "LICENSE"
25
26
  ],
@@ -0,0 +1,29 @@
1
+ ---
2
+ name: portzilla
3
+ description: Coordinate local dev-server ports across parallel agent sessions. Use when starting, stopping, checking, or resolving a local dev-server port.
4
+ ---
5
+
6
+ # Portzilla — dev-server port coordination
7
+
8
+ Use this skill when starting, stopping, checking, or resolving a local dev-server port.
9
+
10
+ ## Prerequisites
11
+
12
+ - `portzilla` must be on PATH. Verify with `portzilla --version` before doing anything else.
13
+
14
+ ## Starting a dev server
15
+
16
+ 1. Inspect the project (its manifest, README, and existing scripts) to choose the right dev-server command for this project.
17
+ 2. The chosen command must consume the assigned port from the `PORTZILLA_PORT` environment variable.
18
+ 3. When a non-empty agent session variable is available, pass it explicitly. Never pass `--session ""`: when the variable is unset or empty, omit `--session` entirely. Use a shell array so empty never becomes an argument: `SESSION_ARGS=(); if [ -n "${PORTZILLA_SESSION:-}" ]; then SESSION_ARGS=(--session "$PORTZILLA_SESSION"); fi` in OpenCode, or `SESSION_ARGS=(); if [ -n "${CLAUDE_CODE_SESSION_ID:-}" ]; then SESSION_ARGS=(--session "$CLAUDE_CODE_SESSION_ID"); fi` in Claude Code.
19
+ 4. Launch it in one step with `portzilla run <port> --tag "<what it is>" "${SESSION_ARGS[@]}" -- <command>`. Do not claim the port first — `run` claims it and holds the lease for the server process.
20
+ 5. If the requested port is busy, `run` reassigns to the next free port and reports it on stderr. Always report the actual assigned port (`PORTZILLA_PORT`) to the user, especially when it differs from the requested one.
21
+
22
+ ## Inspecting and stopping
23
+
24
+ - Check a single port with `portzilla who <port>`; list everything with `portzilla ls`.
25
+ - Release a port only when you explicitly know it is yours to release (the user named it, or your own session claimed it): confirm ownership with `who` first, then `portzilla release <port>`.
26
+
27
+ ## Kill-guard setup
28
+
29
+ This skill does not set up kill protection. If explicitly asked for kill-guard or hook setup, direct that request to `portzilla init opencode` instead.