IW-682: Port allocation for worktrees (iw port-slot) #757

Merged

mph merged 17 commits from IW-682 into main 2026-10-08 06:22:39 +00:00

Conversation 0 Commits 17 Files changed 32 +3464 -54

claude commented 2026-10-08 02:53:36 +00:00

Member

Copy link

Summary

iw-cli gives each worktree a port slot: a whole number unique among the worktrees of one repository. The main checkout holds 0; a linked worktree claims the lowest free slot from 1. A project start hook computes its ports as base + slot × step and no longer needs its own allocator (the generic form of medeca-modul-poptavky find_next_offset).

Changes

• Phase 1 (#752), slot model + slot store: PortSlot, PortSlots.lowestFree, PortSlot.port(base, step), the iw-port-slot.json format and PortSlotError (core/model/PortSlot.scala). WorktreePortSlots.claim/list (core/adapters/WorktreePortSlots.scala) store the slot in the per-worktree git dir, discover other worktrees with git worktree list, and hold a cross-process lock in the common git dir. The atomic file write is extracted from WorktreeServices into AtomicFile, and both stores use it.
• Phase 2 (#753), iw port-slot claim|list + docs: PortSlotOps capability on CommandEnv, PortSlotCommand, commands/port-slot.scala, a README row, and a "Port slots" section plus a rewritten example hook in docs/worktree-services.md.

git worktree remove / iw rm releases the slot with no extra step. A claim is idempotent and atomic across processes.

Testing

• Unit: PortSlotTest, AtomicFileTest, ServiceDeclarationTest, CommandDeclarationTest.
• Harness: PortSlotHarnessTest.
• Integration: WorktreePortSlotsItest (real git worktrees).
• E2E: test/port-slot.bats (claim, list, not-a-checkout, a start hook that claims and declares with the slot free after iw rm, help).
• Pre-push checks (core compile with warnings as errors, scalafix, unit tests, command compile) passed on this head.

Review notes

• The docs example hook says // REQUIRES: iw-cli >= 0.21.0; VERSION is 0.20.0. The release that ships this must be 0.21.0, or the header must change.
• Follow-ups filed: #440 and #585 (comments), #754, #755, #756.
• Review packet: project-management/issues/IW-682/review-packet.md.

Release notes

Datum: 2026-10-08

Každá pracovní kopie projektu teď od iw-cli dostane vlastní číslo, které žádná jiná pracovní kopie téhož repozitáře nemá. Projekt z něj snadno spočítá porty pro své služby, a tak už se nestane, že by dvě souběžně spuštěné pracovní kopie obsadily stejný port. Projekty už nemusí psát a udržovat vlastní skripty, které hledají volné místo mezi ostatními pracovními kopiemi.

Hlavní kopie repozitáře má vždy číslo nula. Každá další pracovní kopie si při prvním vyžádání vezme nejnižší volné číslo od jedničky výš a při každém dalším vyžádání dostane totéž číslo znovu. Projekt si sám zvolí výchozí port a rozestup, například výchozí port 8085 s rozestupem 100 dá první pracovní kopii port 8185. Když se pracovní kopie odstraní, její číslo se samo uvolní a další nová kopie ho může použít. Žádný úklid navíc není potřeba. Ani když se dvě pracovní kopie zakládají ve stejnou chvíli, nedostanou stejné číslo.

Číslo si vyžádá spouštěcí skript projektu, buď přímo v kódu, nebo novým příkazem iw port-slot. Ten také umí vypsat, která pracovní kopie drží které číslo. Dokumentace k deklaraci služeb teď ukazuje celý postup na příkladu: skript si vyžádá číslo, spočítá z něj porty a ohlásí služby, na které pak odkazuje přehled.

Projekty, které si porty dosud počítaly samy, například pomocí souboru s posunem portů, mohou přejít postupně. Nový mechanismus jejich dosavadní soubory nevidí, proto je vhodné pracovní kopie po přechodu založit znovu, nebo do té doby oba způsoby nechat na různých výchozích portech. Číslování platí vždy pro jeden repozitář: pokud má na jednom počítači stejný projekt naklonovaný víc lidí, měl by každý klon používat jiný výchozí port.

🤖 Generated with Claude Code

Closes #682

## Summary iw-cli gives each worktree a **port slot**: a whole number unique among the worktrees of one repository. The main checkout holds 0; a linked worktree claims the lowest free slot from 1. A project start hook computes its ports as `base + slot × step` and no longer needs its own allocator (the generic form of medeca-modul-poptavky `find_next_offset`). ## Changes - **Phase 1 (#752), slot model + slot store:** `PortSlot`, `PortSlots.lowestFree`, `PortSlot.port(base, step)`, the `iw-port-slot.json` format and `PortSlotError` (`core/model/PortSlot.scala`). `WorktreePortSlots.claim`/`list` (`core/adapters/WorktreePortSlots.scala`) store the slot in the per-worktree git dir, discover other worktrees with `git worktree list`, and hold a cross-process lock in the common git dir. The atomic file write is extracted from `WorktreeServices` into `AtomicFile`, and both stores use it. - **Phase 2 (#753), `iw port-slot claim|list` + docs:** `PortSlotOps` capability on `CommandEnv`, `PortSlotCommand`, `commands/port-slot.scala`, a README row, and a "Port slots" section plus a rewritten example hook in `docs/worktree-services.md`. `git worktree remove` / `iw rm` releases the slot with no extra step. A claim is idempotent and atomic across processes. ## Testing - Unit: `PortSlotTest`, `AtomicFileTest`, `ServiceDeclarationTest`, `CommandDeclarationTest`. - Harness: `PortSlotHarnessTest`. - Integration: `WorktreePortSlotsItest` (real git worktrees). - E2E: `test/port-slot.bats` (claim, list, not-a-checkout, a start hook that claims and declares with the slot free after `iw rm`, help). - Pre-push checks (core compile with warnings as errors, scalafix, unit tests, command compile) passed on this head. ## Review notes - The docs example hook says `// REQUIRES: iw-cli >= 0.21.0`; `VERSION` is 0.20.0. The release that ships this must be 0.21.0, or the header must change. - Follow-ups filed: #440 and #585 (comments), #754, #755, #756. - Review packet: `project-management/issues/IW-682/review-packet.md`. ## Release notes **Datum:** 2026-10-08 Každá pracovní kopie projektu teď od iw-cli dostane vlastní číslo, které žádná jiná pracovní kopie téhož repozitáře nemá. Projekt z něj snadno spočítá porty pro své služby, a tak už se nestane, že by dvě souběžně spuštěné pracovní kopie obsadily stejný port. Projekty už nemusí psát a udržovat vlastní skripty, které hledají volné místo mezi ostatními pracovními kopiemi. Hlavní kopie repozitáře má vždy číslo nula. Každá další pracovní kopie si při prvním vyžádání vezme nejnižší volné číslo od jedničky výš a při každém dalším vyžádání dostane totéž číslo znovu. Projekt si sám zvolí výchozí port a rozestup, například výchozí port 8085 s rozestupem 100 dá první pracovní kopii port 8185. Když se pracovní kopie odstraní, její číslo se samo uvolní a další nová kopie ho může použít. Žádný úklid navíc není potřeba. Ani když se dvě pracovní kopie zakládají ve stejnou chvíli, nedostanou stejné číslo. Číslo si vyžádá spouštěcí skript projektu, buď přímo v kódu, nebo novým příkazem `iw port-slot`. Ten také umí vypsat, která pracovní kopie drží které číslo. Dokumentace k deklaraci služeb teď ukazuje celý postup na příkladu: skript si vyžádá číslo, spočítá z něj porty a ohlásí služby, na které pak odkazuje přehled. Projekty, které si porty dosud počítaly samy, například pomocí souboru s posunem portů, mohou přejít postupně. Nový mechanismus jejich dosavadní soubory nevidí, proto je vhodné pracovní kopie po přechodu založit znovu, nebo do té doby oba způsoby nechat na různých výchozích portech. Číslování platí vždy pro jeden repozitář: pokud má na jednom počítači stejný projekt naklonovaný víc lidí, měl by každý klon používat jiný výchozí port. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Closes #682

claude added 17 commits 2026-10-08 02:53:36 +00:00

workflow(wf): Create analysis for IW-682 ... d7ab28d6bd

Port allocation for worktrees, so project start hooks need not compute their own ports

Artifacts:
- analysis.md
- issue.md

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B8ZD5foFWAE2zV1xYojPMa

chore(IW-682): update review-state to tasks_ready 122482cfc8

workflow(wf): Create task index for IW-682 ... fee6d07972

Port allocation for worktrees, so project start hooks need not compute their own ports

Artifacts:
- tasks.md
- review-state.json (tasks_ready)

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B8ZD5foFWAE2zV1xYojPMa

docs(IW-682): intake verdict — agent-ready ... 462a992030

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B8ZD5foFWAE2zV1xYojPMa

Merge remote-tracking branch 'origin/main' into IW-682 f2be9ba456

Merge remote-tracking branch 'origin/main' into IW-682 2b88f896f7

chore(IW-682): move review-state card out of the tree b490efa9c4

Phase 1: context ready ... aad2597c5b

Issue: IW-682
Phase: 1 - Slot model + slot store

This commit marks the checkpoint for phase 1 context generation.
Use wf-implement IW-682 to return to this point.

The analysis now names GitDirReader (IW-702) and AtomicFile as the shared
helpers, the --separate-git-dir main checkout rule, and the corrected reason
for an idempotent claim.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

workflow(wf): Generate Phase 1 tasks for IW-682 ... 23f6153b31

Slot model + slot store

Artifacts:
- phase-01-tasks.md

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Phase 1: Slot model + slot store (#752) 55f84fd4e3

chore(IW-682): mark phase 01 complete in tasks.md e33fdf0a9f

Phase 2: context ready ... f04f9505b3

Issue: IW-682
Phase: 2 - `iw port-slot` + docs

This commit marks the checkpoint for phase 2 context generation.
Use wf-implement IW-682 to return to this point.

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

workflow(wf): Generate Phase 2 tasks for IW-682 ... 4374d31c1b

`iw port-slot` + docs

Artifacts:
- phase-02-tasks.md

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Phase 2: iw port-slot + docs (#753) 91b0dfb679

chore(IW-682): mark phase 02 complete in tasks.md bb08eea848

chore(IW-682): file follow-ups (#440, #585, #754, #755, #756) ... fdeedfa74f

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs(IW-682): review packet and release notes ... 6eb87a459c

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

mph merged commit 567bd57d76 into main 2026-10-08 06:22:39 +00:00

mph referenced this pull request from a commit 2026-10-08 06:22:39 +00:00

Merge pull request 'IW-682: Port allocation for worktrees (iw port-slot)' (#757) from IW-682 into main

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

agent-ready

  

bug

Something isn't working

  

contract

Run the tool-contract suite on this PR

  

documentation

Improvements or additions to documentation

  

duplicate

This issue or pull request already exists

  

enhancement

New feature or request

  

good first issue

Good for newcomers

  

help wanted

Extra attention is needed

  

invalid

This doesn't seem right

  

needs-human

  

needs-input

Intake asked the human a question on the issue; waiting for the answer

  

question

Further information is requested

  

wontfix

This will not be worked on

No labels

agent-ready

bug

contract

documentation

duplicate

enhancement

good first issue

help wanted

invalid

needs-human

needs-input

question

wontfix

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

iterative-works/iw-cli!757

No description provided.