portzilla 0.3.0 → 0.5.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 +54 -6
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -13,6 +13,7 @@
|
|
|
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
|
+
[](https://m8ven.ai/mcp/011010-portzilla-qdocjc?s=readme)
|
|
16
17
|
</p>
|
|
17
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**.
|
|
@@ -104,7 +105,7 @@ $ cargo install --path .
|
|
|
104
105
|
```console
|
|
105
106
|
$ curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/011010/portzilla/main/scripts/install.sh | sh
|
|
106
107
|
# specific version / directory:
|
|
107
|
-
$ curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/011010/portzilla/main/scripts/install.sh | PORTZILLA_VERSION=0.
|
|
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
|
|
108
109
|
```
|
|
109
110
|
|
|
110
111
|
**npm** (same native binary):
|
|
@@ -188,7 +189,19 @@ For agents with MCP access (Claude Code, etc.) — typed JSON in/out instead of
|
|
|
188
189
|
$ claude mcp add portzilla -- portzilla serve --mcp
|
|
189
190
|
```
|
|
190
191
|
|
|
191
|
-
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)**.
|
|
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)**.
|
|
193
|
+
|
|
194
|
+
## Audit history
|
|
195
|
+
|
|
196
|
+
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.
|
|
197
|
+
|
|
198
|
+
```console
|
|
199
|
+
$ portzilla history --json
|
|
200
|
+
$ portzilla history --session my-session --event guard_denied
|
|
201
|
+
$ portzilla history clear
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
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)**.
|
|
192
205
|
|
|
193
206
|
## Kill guard
|
|
194
207
|
|
|
@@ -203,17 +216,52 @@ Recognizes `kill <pid>`, `pkill`/`killall`, `lsof -ti:<port> | xargs kill`, `fus
|
|
|
203
216
|
| **Gemini CLI** | `BeforeTool` — `portzilla hook gemini` | Yes (Deny), no Warn channel | No |
|
|
204
217
|
| **Codex CLI** | `PreToolUse` — `portzilla hook codex` | Yes (Deny + Warn via `additionalContext`) | No |
|
|
205
218
|
| **Kimi CLI** | `PreToolUse` — `portzilla hook kimi` | Yes (stderr on exit 2) | No |
|
|
206
|
-
| **OpenCode** | Plugin shim — `portzilla init opencode` | Yes (Deny
|
|
219
|
+
| **OpenCode** | Plugin shim, V2 API — `portzilla init opencode` | Yes (Deny) | No (V2 gives no session id to shell commands) |
|
|
207
220
|
| **Windsurf** | `pre_run_command` — `portzilla hook windsurf` | Yes (stderr) | No |
|
|
208
221
|
| **Anything else** | `portzilla guard -- <cmd>` | N/A (exit 2) | **Yes** (`--session` / `$PORTZILLA_SESSION`) |
|
|
209
222
|
|
|
210
|
-
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.
|
|
223
|
+
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.
|
|
211
224
|
|
|
212
225
|
Full harness setup, `sh -c` unwrapping rules, and fail-open/closed semantics → **[docs/GUARD.md](docs/GUARD.md)**.
|
|
213
226
|
|
|
227
|
+
### File intents (OpenCode)
|
|
228
|
+
|
|
229
|
+
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
|
+
|
|
231
|
+
The OpenCode shim asks for an intent on every `write`/`edit` before the tool runs, and sends the pending edit with the request:
|
|
232
|
+
|
|
233
|
+
- The first session to edit a file claims it for 30 minutes (`PORTZILLA_INTENT_TTL_SECS` overrides the window).
|
|
234
|
+
- A session that edits it again refreshes its own claim.
|
|
235
|
+
- 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.
|
|
236
|
+
- 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.
|
|
237
|
+
- A denied attempt claims nothing, so a blocked session cannot take the file by retrying.
|
|
238
|
+
|
|
239
|
+
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.
|
|
240
|
+
|
|
241
|
+
Humans can inspect and clear claims without waiting for the TTL:
|
|
242
|
+
|
|
243
|
+
```console
|
|
244
|
+
$ portzilla intent claim src/auth.rs --session "$CLAUDE_CODE_SESSION_ID"
|
|
245
|
+
claimed /repo/src/auth.rs for session ... (expires in 1800s)
|
|
246
|
+
|
|
247
|
+
$ portzilla intent who src/auth.rs
|
|
248
|
+
/repo/src/auth.rs is held by session ... (age 12s, expires in 1788s)
|
|
249
|
+
|
|
250
|
+
$ portzilla intent ls
|
|
251
|
+
KEY SESSION AGE EXPIRES
|
|
252
|
+
...
|
|
253
|
+
|
|
254
|
+
$ portzilla intent release src/auth.rs --session "$CLAUDE_CODE_SESSION_ID"
|
|
255
|
+
released /repo/src/auth.rs for session ...
|
|
256
|
+
```
|
|
257
|
+
|
|
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)**.
|
|
259
|
+
|
|
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.
|
|
261
|
+
|
|
214
262
|
## Data file & config
|
|
215
263
|
|
|
216
|
-
Resolution order: `PORTZILLA_DATA_DIR` → `$XDG_DATA_HOME/portzilla` → `~/.local/share/portzilla`. State at `leases.json` (atomic write + `leases.json.lock`).
|
|
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.
|
|
217
265
|
|
|
218
266
|
`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)**.
|
|
219
267
|
|
|
@@ -229,7 +277,7 @@ Resolution order: `PORTZILLA_DATA_DIR` → `$XDG_DATA_HOME/portzilla` → `~/.lo
|
|
|
229
277
|
|
|
230
278
|
## Roadmap
|
|
231
279
|
|
|
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).
|
|
280
|
+
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).
|
|
233
281
|
|
|
234
282
|
## License
|
|
235
283
|
|