portzilla 0.4.0 → 0.6.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.
Files changed (2) hide show
  1. package/README.md +96 -12
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -5,7 +5,7 @@
5
5
  <h1 align="center">portzilla</h1>
6
6
 
7
7
  <p align="center">
8
- <strong>Lease registry for localhost ports — stop killing your sibling's dev server.</strong>
8
+ <strong>Coordination layer for parallel AI agent sessions — ports, files, and worktree environments.</strong>
9
9
  </p>
10
10
 
11
11
  <p align="center">
@@ -13,13 +13,19 @@
13
13
  <a href="https://crates.io/crates/portzilla"><img src="https://img.shields.io/crates/v/portzilla" alt="crates.io"></a>
14
14
  <a href="https://www.npmjs.com/package/portzilla"><img src="https://img.shields.io/npm/v/portzilla" alt="npm"></a>
15
15
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT"></a>
16
+ [![M8ven Score](https://m8ven.ai/badge/mcp/011010-portzilla-qdocjc?v=2e641775b25eeb046db492cd7a4d7c5e)](https://m8ven.ai/mcp/011010-portzilla-qdocjc?s=readme)
16
17
  </p>
17
18
 
18
- > AI coding agents (Claude Code, Cursor, etc.) run parallel sessions in git worktrees — each starting its own dev server. Today they coordinate by killing whatever is on a port. `portzilla` is the layer that **prevents the conflict**.
19
+ > AI coding agents (Claude Code, Cursor, etc.) run parallel sessions in git worktrees — each starting its own dev server, editing the same files, and pointing at the same database. Today they coordinate by killing whatever is on a port. `portzilla` is the layer that **prevents the conflict**.
19
20
 
20
- - **Claim, don't kill** — `portzilla claim 3000 --tag next-dev` gives you a port with owner PID + purpose tag. Conflicts and already-bound ports get the next available port instead of stealing.
21
- - **Ask before you kill** — `portzilla who 3000` tells you who owns a port. JSON everywhere so agents can consume it directly.
22
- - **Guard by default** — intercepts `kill`, `lsof | xargs kill`, `fuser -k`, `kill-port` and blocks kills against another session's live lease.
21
+ | What collides | What portzilla gives you | Start here |
22
+ |---|---|---|
23
+ | A port both sessions want | A lease with owner PID and purpose tag. Conflicts get the next free port instead of a kill | `portzilla claim 3000 --tag next-dev` |
24
+ | A port another agent wants to kill | A guard that intercepts `kill`, `lsof \| xargs kill`, `fuser -k`, `kill-port` and blocks kills against another session's live lease | `portzilla init <harness>` |
25
+ | A file both sessions edit | A file intent. A proven conflict is denied; a clean merge is allowed with a warning; hooks do it automatically on OpenCode and Claude Code | `portzilla intent claim src/auth.ts` |
26
+ | A database and a `target/` directory both sessions share | An environment slot: its own ports, cache directories, `.env.portzilla`, and a database provisioned by your own commands | `portzilla slot up auth` |
27
+
28
+ Every layer speaks JSON and is exposed over MCP, so an agent calls it as a tool instead of parsing text. Everything is a single daemon-less binary.
23
29
 
24
30
  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
31
 
@@ -34,7 +40,10 @@ Port allocators and proxies such as [Portless](https://portless.sh) solve addres
34
40
  - [Agent skill](#agent-skill)
35
41
  - [Watch mode](#watch-mode)
36
42
  - [MCP server](#mcp-server)
43
+ - [Audit history](#audit-history)
37
44
  - [Kill guard](#kill-guard)
45
+ - [File intents](#file-intents)
46
+ - [Environment slots](#environment-slots)
38
47
  - [Data file & config](#data-file--config)
39
48
  - [Limitations](#limitations)
40
49
 
@@ -104,7 +113,7 @@ $ cargo install --path .
104
113
  ```console
105
114
  $ curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/011010/portzilla/main/scripts/install.sh | sh
106
115
  # specific version / directory:
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
116
+ $ curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/011010/portzilla/main/scripts/install.sh | PORTZILLA_VERSION=0.6.0 PORTZILLA_INSTALL_DIR=/usr/local/bin sh
108
117
  ```
109
118
 
110
119
  **npm** (same native binary):
@@ -125,8 +134,14 @@ Binaries for Linux x86_64/ARM64, macOS Intel/Apple Silicon, Windows x86_64/ARM64
125
134
  | `portzilla prune` | Remove all leases whose PID is dead |
126
135
  | `portzilla run <PORT> --tag <TAG> [--session <S>] -- <cmd...>` | Claim a port and run a server with it; the lease follows the child PID |
127
136
  | `portzilla watch [--interval <SECONDS>]` | Repeatedly prune leases whose recorded PID is dead |
137
+ | `portzilla guard -- <cmd...>` | Run a command with the kill guard applied, for harnesses without hooks |
138
+ | `portzilla init <harness>` | Print the hook/plugin snippet to install; prose on stderr, snippet on stdout |
139
+ | `portzilla serve --mcp` | Run the MCP server on stdio |
140
+ | `portzilla intent claim\|who\|ls\|release\|history` | File intents: claim a path, inspect the holder, release early, read the journal |
141
+ | `portzilla slot up\|env\|run\|ls\|show\|down\|prune` | Environment slots: ports, cache dirs, `.env.portzilla`, database |
142
+ | `portzilla history [--json]` | Bounded lease and guard event journal |
128
143
 
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)**.
144
+ Data-producing commands are file-locked and support `--json`. Full flags, conflict semantics, exit codes and JSON shapes → **[docs/CLI.md](docs/CLI.md)**. Slots have their own reference: **[docs/SLOTS.md](docs/SLOTS.md)**.
130
145
 
131
146
  ## Agent skill
132
147
 
@@ -188,7 +203,9 @@ For agents with MCP access (Claude Code, etc.) — typed JSON in/out instead of
188
203
  $ claude mcp add portzilla -- portzilla serve --mcp
189
204
  ```
190
205
 
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)**.
206
+ Exposes `claim`, `who`, `ls`, `release`, `prune`, read-only `history`, and the four file-intent tools `intent_claim`, `intent_who`, `intent_ls`, `intent_release`, plus read-only `intent_history`, with the same JSON shapes as `--json`. See **[docs/CLI.md#mcp-server](docs/CLI.md#mcp-server)**.
207
+
208
+ The intent tools are the only file protection available on harnesses without an edit hook (Cursor, Gemini CLI, Codex, Windsurf): the agent calls `intent_claim` before editing and `intent_release` when it is done. They are cooperative, so they complement rather than replace the OpenCode and Claude Code hooks. **Pass a session string identical to the one your harness gives the hooks**, otherwise your own claims look foreign to the guard.
192
209
 
193
210
  ## Audit history
194
211
 
@@ -202,6 +219,8 @@ $ portzilla history clear
202
219
 
203
220
  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)**.
204
221
 
222
+ File intents keep their own journal of the same size in `intents.json`, recording `claim_created`, `claim_refreshed`, `claim_taken_over` and `released` events next to the claims they describe. Query it with `portzilla intent history --session … --event … --limit …`, or read-only over MCP with `intent_history`. Expired records reaped by a new claim are housekeeping and are not logged.
223
+
205
224
  ## Kill guard
206
225
 
207
226
  Makes *checking ownership the default* — blocks `kill` commands that would kill another session's live leased process.
@@ -210,22 +229,87 @@ Recognizes `kill <pid>`, `pkill`/`killall`, `lsof -ti:<port> | xargs kill`, `fus
210
229
 
211
230
  | Harness | Hook | Deny reaches model? | Own-lease? |
212
231
  |---------|------|---------------------|------------|
213
- | **Claude Code** | `PreToolUse` — `portzilla hook claude-code` | Yes (`permissionDecisionReason`) | **Yes** (`$CLAUDE_CODE_SESSION_ID`) |
232
+ | **Claude Code** | `PreToolUse` + `PostToolUse` — `portzilla hook claude-code` | Yes (`permissionDecisionReason`; clean-merge context via `PostToolUse`) | **Yes** (`$CLAUDE_CODE_SESSION_ID`) |
214
233
  | **Cursor** | `beforeShellExecution` — `portzilla hook cursor` | Likely (`agent_message`) | No |
215
234
  | **Gemini CLI** | `BeforeTool` — `portzilla hook gemini` | Yes (Deny), no Warn channel | No |
216
235
  | **Codex CLI** | `PreToolUse` — `portzilla hook codex` | Yes (Deny + Warn via `additionalContext`) | No |
217
236
  | **Kimi CLI** | `PreToolUse` — `portzilla hook kimi` | Yes (stderr on exit 2) | No |
218
- | **OpenCode** | Plugin shim — `portzilla init opencode` | Yes (Deny + Warn) | **Yes** (`$PORTZILLA_SESSION`) |
237
+ | **OpenCode** | Plugin shim, V2 API — `portzilla init opencode` | Yes (Deny) | No (V2 gives no session id to shell commands) |
219
238
  | **Windsurf** | `pre_run_command` — `portzilla hook windsurf` | Yes (stderr) | No |
220
239
  | **Anything else** | `portzilla guard -- <cmd>` | N/A (exit 2) | **Yes** (`--session` / `$PORTZILLA_SESSION`) |
221
240
 
222
- Setup: `portzilla init <harness>` prints the snippet to add — never writes files for you. Guard fails open by default; `PORTZILLA_FAIL_CLOSED=1` opts into fail-closed.
241
+ Setup: `portzilla init <harness>` prints the snippet to add — never writes files for you. The snippet goes to stdout and the instructions to stderr, so a redirect such as `portzilla init opencode > .opencode/plugin/portzilla.js` saves exactly the file. Guard fails open by default; `PORTZILLA_FAIL_CLOSED=1` opts into fail-closed.
223
242
 
224
243
  Full harness setup, `sh -c` unwrapping rules, and fail-open/closed semantics → **[docs/GUARD.md](docs/GUARD.md)**.
225
244
 
245
+ ### File intents
246
+
247
+ Agents in parallel worktrees also collide on *files*: two sessions editing `src/auth.rs` produce a merge conflict that only surfaces at review time. File intents are the same lease idea applied to a path.
248
+
249
+ Three delivery paths, same store and same verdicts:
250
+
251
+ | Harness | How the check happens |
252
+ |---|---|
253
+ | OpenCode | Plugin shim asks on every `write`/`edit` and sends the pending edit |
254
+ | Claude Code | `PreToolUse` on `Write`/`Edit`; `PostToolUse` delivers the clean-merge warning |
255
+ | Everything with MCP | `intent_claim` / `intent_who` / `intent_ls` / `intent_release` — cooperative, the agent decides to call them |
256
+
257
+ What the guard does with the pending edit:
258
+
259
+ - The first session to edit a file claims it for 30 minutes (`PORTZILLA_INTENT_TTL_SECS` overrides the window).
260
+ - A session that edits it again refreshes its own claim.
261
+ - A *different* live session triggers a conflict check against the holder's working copy. A real conflict is denied, and the reason says the edit conflicts. An edit that merges cleanly is allowed, the holder keeps its claim, and the model reads a warning on the tool result that names the holder.
262
+ - Anything the check cannot prove — a v1 record with no recorded location, a git failure, an incomplete edit payload — is denied exactly as before. The check is fail-safe: the softer verdict applies only when cleanliness has been proven.
263
+ - A denied attempt claims nothing, so a blocked session cannot take the file by retrying.
264
+
265
+ The key is `<git-common-dir>:<repo-relative-path>`. The same relative file in two worktrees of one repository is one key; the same absolute path in a different repository is not. Outside a repository the key is the canonical absolute path.
266
+
267
+ Humans can inspect and clear claims without waiting for the TTL:
268
+
269
+ ```console
270
+ $ portzilla intent claim src/auth.rs --session "$CLAUDE_CODE_SESSION_ID"
271
+ claimed /repo/src/auth.rs for session ... (expires in 1800s)
272
+
273
+ $ portzilla intent who src/auth.rs
274
+ /repo/src/auth.rs is held by session ... (age 12s, expires in 1788s)
275
+
276
+ $ portzilla intent ls
277
+ KEY SESSION AGE EXPIRES
278
+ ...
279
+
280
+ $ portzilla intent release src/auth.rs --session "$CLAUDE_CODE_SESSION_ID"
281
+ released /repo/src/auth.rs for session ...
282
+
283
+ $ portzilla intent history --session "$CLAUDE_CODE_SESSION_ID"
284
+ SEQ AT EVENT SESSION KEY
285
+ ...
286
+ ```
287
+
288
+ `claim` records where the caller's working copy lives, so a claim made by hand is conflict-checkable by the OpenCode guard too. The intent file is at schema v3: it also holds a bounded journal of claim and release events. v1 and v2 files are read and upgraded on the next write (their journal starts at sequence 1), but an older portzilla binary cannot read a v3 file and must be upgraded before sharing a data directory. Invalid TTLs (outside 1–86400 seconds) are refused. Full flags, exit codes and JSON shapes → **[docs/CLI.md](docs/CLI.md#file-intents)**.
289
+
290
+ Limits, stated plainly: OpenCode and Claude Code enforce automatically; every other harness depends on the agent calling the MCP tools. The conflict proof runs `git merge-file`, so it needs git and both working copies on the same machine.
291
+
292
+ One consequence worth knowing: ownership is per *session*, and every `opencode run` invocation is a new session. In the TUI a conversation keeps its session for its whole life, but scripted runs block each other on the same file until the TTL lapses. `portzilla intent ls` shows the holder and `portzilla intent release <path> --session <id>` frees it immediately.
293
+
294
+ ## Environment slots
295
+
296
+ Ports and files are not the only shared resources: two worktrees of one project also collide on the database they both point at and on the `target/` directory Cargo serialises behind its lock.
297
+
298
+ A **slot** gives one worktree its own ports, cache directories, `.env.portzilla`, and — through commands you configure — its own database:
299
+
300
+ ```console
301
+ $ portzilla slot up auth
302
+ $ portzilla slot run auth -- npm test
303
+ $ portzilla slot down auth
304
+ ```
305
+
306
+ Configured in `portzilla.toml` at the worktree root; `up` is transactional and rolls back completely on failure; `down` is retryable and refuses to destroy a database it could not deprovision. No daemon, no containers, and your credentials never pass through Portzilla.
307
+
308
+ Full reference, including SQLite and Postgres recipes → **[docs/SLOTS.md](docs/SLOTS.md)**.
309
+
226
310
  ## Data file & config
227
311
 
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.
312
+ Resolution order: `PORTZILLA_DATA_DIR` → `$XDG_DATA_HOME/portzilla` → `~/.local/share/portzilla`. Three independent stores, each written atomically behind its own lock: `leases.json` (leases plus the port/guard journal), `intents.json` (file claims plus their journal), and `slots.json` (environment slots). No store is shared with another, so a corrupt or locked file never takes the others down with it.
229
313
 
230
314
  `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)**.
231
315
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "portzilla",
3
- "version": "0.4.0",
3
+ "version": "0.6.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",