portzilla 0.5.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 +62 -14
  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">
@@ -16,11 +16,16 @@
16
16
  [![M8ven Score](https://m8ven.ai/badge/mcp/011010-portzilla-qdocjc?v=2e641775b25eeb046db492cd7a4d7c5e)](https://m8ven.ai/mcp/011010-portzilla-qdocjc?s=readme)
17
17
  </p>
18
18
 
19
- > 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**.
20
20
 
21
- - **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.
22
- - **Ask before you kill** — `portzilla who 3000` tells you who owns a port. JSON everywhere so agents can consume it directly.
23
- - **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.
24
29
 
25
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.
26
31
 
@@ -35,7 +40,10 @@ Port allocators and proxies such as [Portless](https://portless.sh) solve addres
35
40
  - [Agent skill](#agent-skill)
36
41
  - [Watch mode](#watch-mode)
37
42
  - [MCP server](#mcp-server)
43
+ - [Audit history](#audit-history)
38
44
  - [Kill guard](#kill-guard)
45
+ - [File intents](#file-intents)
46
+ - [Environment slots](#environment-slots)
39
47
  - [Data file & config](#data-file--config)
40
48
  - [Limitations](#limitations)
41
49
 
@@ -105,7 +113,7 @@ $ cargo install --path .
105
113
  ```console
106
114
  $ curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/011010/portzilla/main/scripts/install.sh | sh
107
115
  # specific version / directory:
108
- $ curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/011010/portzilla/main/scripts/install.sh | PORTZILLA_VERSION=0.5.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
109
117
  ```
110
118
 
111
119
  **npm** (same native binary):
@@ -126,8 +134,14 @@ Binaries for Linux x86_64/ARM64, macOS Intel/Apple Silicon, Windows x86_64/ARM64
126
134
  | `portzilla prune` | Remove all leases whose PID is dead |
127
135
  | `portzilla run <PORT> --tag <TAG> [--session <S>] -- <cmd...>` | Claim a port and run a server with it; the lease follows the child PID |
128
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 |
129
143
 
130
- 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)**.
131
145
 
132
146
  ## Agent skill
133
147
 
@@ -189,7 +203,9 @@ For agents with MCP access (Claude Code, etc.) — typed JSON in/out instead of
189
203
  $ claude mcp add portzilla -- portzilla serve --mcp
190
204
  ```
191
205
 
192
- 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.
193
209
 
194
210
  ## Audit history
195
211
 
@@ -203,6 +219,8 @@ $ portzilla history clear
203
219
 
204
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)**.
205
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
+
206
224
  ## Kill guard
207
225
 
208
226
  Makes *checking ownership the default* — blocks `kill` commands that would kill another session's live leased process.
@@ -211,7 +229,7 @@ Recognizes `kill <pid>`, `pkill`/`killall`, `lsof -ti:<port> | xargs kill`, `fus
211
229
 
212
230
  | Harness | Hook | Deny reaches model? | Own-lease? |
213
231
  |---------|------|---------------------|------------|
214
- | **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`) |
215
233
  | **Cursor** | `beforeShellExecution` — `portzilla hook cursor` | Likely (`agent_message`) | No |
216
234
  | **Gemini CLI** | `BeforeTool` — `portzilla hook gemini` | Yes (Deny), no Warn channel | No |
217
235
  | **Codex CLI** | `PreToolUse` — `portzilla hook codex` | Yes (Deny + Warn via `additionalContext`) | No |
@@ -224,11 +242,19 @@ Setup: `portzilla init <harness>` prints the snippet to add — never writes fil
224
242
 
225
243
  Full harness setup, `sh -c` unwrapping rules, and fail-open/closed semantics → **[docs/GUARD.md](docs/GUARD.md)**.
226
244
 
227
- ### File intents (OpenCode)
245
+ ### File intents
228
246
 
229
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.
230
248
 
231
- The OpenCode shim asks for an intent on every `write`/`edit` before the tool runs, and sends the pending edit with the request:
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:
232
258
 
233
259
  - The first session to edit a file claims it for 30 minutes (`PORTZILLA_INTENT_TTL_SECS` overrides the window).
234
260
  - A session that edits it again refreshes its own claim.
@@ -253,15 +279,37 @@ KEY SESSION AGE EXPIRES
253
279
 
254
280
  $ portzilla intent release src/auth.rs --session "$CLAUDE_CODE_SESSION_ID"
255
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
256
304
  ```
257
305
 
258
- `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 v2: v1 files are read and upgraded on the next write, but an older portzilla binary cannot read a v2 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)**.
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.
259
307
 
260
- Limits, stated plainly: only OpenCode is covered today; the other harnesses still get the kill guard alone. The conflict proof runs `git merge-file`, so it needs git and both working copies on the same machine.
308
+ Full reference, including SQLite and Postgres recipes → **[docs/SLOTS.md](docs/SLOTS.md)**.
261
309
 
262
310
  ## Data file & config
263
311
 
264
- 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.
265
313
 
266
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)**.
267
315
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "portzilla",
3
- "version": "0.5.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",