portzilla 0.2.0 → 0.4.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 +40 -6
- package/package.json +2 -1
- package/skills/portzilla/SKILL.md +29 -0
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
|
-
|
|
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
|

|
|
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.
|
|
107
|
+
$ curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/011010/portzilla/main/scripts/install.sh | PORTZILLA_VERSION=0.4.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
|
|
@@ -166,7 +188,19 @@ For agents with MCP access (Claude Code, etc.) — typed JSON in/out instead of
|
|
|
166
188
|
$ claude mcp add portzilla -- portzilla serve --mcp
|
|
167
189
|
```
|
|
168
190
|
|
|
169
|
-
Exposes `claim`, `who`, `ls`, `release`, `prune` as MCP tools with the same JSON shapes as `--json`. See **[docs/CLI.md#mcp-server](docs/CLI.md#mcp-server)**.
|
|
191
|
+
Exposes `claim`, `who`, `ls`, `release`, `prune`, and read-only `history` as MCP tools with the same JSON shapes as `--json`. See **[docs/CLI.md#mcp-server](docs/CLI.md#mcp-server)**.
|
|
192
|
+
|
|
193
|
+
## Audit history
|
|
194
|
+
|
|
195
|
+
Portzilla keeps the latest 10,000 operational events alongside the lease state. Lease changes, managed-process exits, and guard denies/warnings are recorded; guard allows and raw shell commands are not.
|
|
196
|
+
|
|
197
|
+
```console
|
|
198
|
+
$ portzilla history --json
|
|
199
|
+
$ portzilla history --session my-session --event guard_denied
|
|
200
|
+
$ portzilla history clear
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
History is newest-first and supports `--session`, `--port`, `--event`, `--before`, and `--limit`. Hook and guard event writes are best-effort: a journal failure never changes an allow/deny decision. The MCP server exposes the same read-only history query; clearing history is CLI-only. See **[docs/CLI.md#history](docs/CLI.md#history)**.
|
|
170
204
|
|
|
171
205
|
## Kill guard
|
|
172
206
|
|
|
@@ -191,7 +225,7 @@ Full harness setup, `sh -c` unwrapping rules, and fail-open/closed semantics →
|
|
|
191
225
|
|
|
192
226
|
## Data file & config
|
|
193
227
|
|
|
194
|
-
Resolution order: `PORTZILLA_DATA_DIR` → `$XDG_DATA_HOME/portzilla` → `~/.local/share/portzilla`. State at `leases.json` (atomic write + `leases.json.lock`).
|
|
228
|
+
Resolution order: `PORTZILLA_DATA_DIR` → `$XDG_DATA_HOME/portzilla` → `~/.local/share/portzilla`. State at `leases.json` (atomic write + `leases.json.lock`). New writes use the v3 envelope, which stores leases and bounded audit history together.
|
|
195
229
|
|
|
196
230
|
`PORTZILLA_DATA_DIR` isolates tests/CI. `tag` max 1024 chars, `session` max 512, hook stdin capped at 1 MiB. New leases persist `process_start_time` when available; reassignment JSON includes `reassignment_reason` (`lease_conflict` or `os_occupied`). Claims for an explicit PID that does not exist yet are retained as unverified/dead records, not as ownership promises. The normal CLI default attributes a claim to its live parent process. See **[docs/CLI.md](docs/CLI.md)**.
|
|
197
231
|
|
|
@@ -203,11 +237,11 @@ Resolution order: `PORTZILLA_DATA_DIR` → `$XDG_DATA_HOME/portzilla` → `~/.lo
|
|
|
203
237
|
|
|
204
238
|
**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
239
|
|
|
206
|
-
`portzilla` does not
|
|
240
|
+
`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
241
|
|
|
208
242
|
## Roadmap
|
|
209
243
|
|
|
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).
|
|
244
|
+
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 + audit history. 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
245
|
|
|
212
246
|
## License
|
|
213
247
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "portzilla",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.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.
|