portzilla 0.4.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.
Files changed (2) hide show
  1. package/README.md +39 -3
  2. 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
+ [![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
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.4.0 PORTZILLA_INSTALL_DIR=/usr/local/bin sh
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):
@@ -215,14 +216,49 @@ Recognizes `kill <pid>`, `pkill`/`killall`, `lsof -ti:<port> | xargs kill`, `fus
215
216
  | **Gemini CLI** | `BeforeTool` — `portzilla hook gemini` | Yes (Deny), no Warn channel | No |
216
217
  | **Codex CLI** | `PreToolUse` — `portzilla hook codex` | Yes (Deny + Warn via `additionalContext`) | No |
217
218
  | **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`) |
219
+ | **OpenCode** | Plugin shim, V2 API — `portzilla init opencode` | Yes (Deny) | No (V2 gives no session id to shell commands) |
219
220
  | **Windsurf** | `pre_run_command` — `portzilla hook windsurf` | Yes (stderr) | No |
220
221
  | **Anything else** | `portzilla guard -- <cmd>` | N/A (exit 2) | **Yes** (`--session` / `$PORTZILLA_SESSION`) |
221
222
 
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.
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.
223
224
 
224
225
  Full harness setup, `sh -c` unwrapping rules, and fail-open/closed semantics → **[docs/GUARD.md](docs/GUARD.md)**.
225
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
+
226
262
  ## Data file & config
227
263
 
228
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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "portzilla",
3
- "version": "0.4.0",
3
+ "version": "0.5.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",