feat(serve): use deterministic port when running inside a git worktree

[DavideCarvalho]

Summary

When running node ace serve inside a git worktree, the development server now automatically uses a deterministic port derived from the worktree name, so multiple worktrees of the same application can run in parallel without port conflicts.

For example, running the same app in ~/worktrees/feature-login and ~/worktrees/feature-checkout will automatically bind to different ports, always the same for the same worktree.

Why this is needed

Working with multiple git worktrees of the same project is the standard way to develop several features/branches side by side. The problem: every worktree reads the same .env (or the default port 3333), so starting node ace serve in a second worktree fails with EADDRINUSE — you have to manually change the port (editing .env or exporting PORT) every time, and that change is not shared/predictable across teammates.

A deterministic port derived from the worktree name solves this without touching .env:

• Each worktree always binds to the same port (stable hash), so the same command can be run over and over.
• Two different worktrees get different ports, so they can run in parallel.
• The behavior is automatic (no flags to remember) and opt-out via --no-worktree-port.

So the feature exists to answer: "start the dev server in this worktree, on a port that is unique to this worktree, without manual configuration."

How it works

• The command detects if the application root is inside a linked git worktree by checking for a .git file (linked worktrees have a .git file pointing to the main repo, while the main checkout has a .git directory).
• The worktree name is derived from the directory holding the .git file (walking up when the app lives in a nested directory).
• The port is computed as basePort + (hash(worktreeName) % 1000), where basePort is read from the app dot-env files (PORT) and defaults to 3333. The hash is stable, so the same worktree always resolves to the same port.
• The command sets process.env.PORT before starting the dev server — the assembler already prefers process.env.PORT, so no .env file is touched (git stays clean).

Usage

node ace serve              # auto-detects the worktree and picks a deterministic port
node ace serve --no-worktree-port  # disables the behavior

Changes

• commands/serve.ts — worktree detection + port override + --no-worktree-port flag + help text
• src/helpers/worktree.ts — getWorktreeName, getBasePort, computeWorktreePort
• tests/helpers/worktree.spec.ts — unit tests for the helpers
• tests/commands/serve.spec.ts — integration tests for the serve behavior

Notes

• No new dependency: uses @adonisjs/env (already a dependency of core) and the built-in node:crypto/node:fs.
• When the app is not inside a linked worktree (main checkout or non-git directory), the command behaves exactly as before.

[DavideCarvalho]

Moved into #5136 to keep both features in a single PR.

[p3drosola]

Just pass PORT=1234 node ace serve it's up to your env harness script to calculate the right port. It shouldn't be a concern of the framework IMO