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 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.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 start/stop servers, enforce firewall/sandbox, or coordinate across machines.
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.2.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.