Portle

Portle is a mixed-language monorepo with a Go runtime/proxy core and an npm distribution wrapper.

Monorepo layout

.
├── go/portle                 # Go core binary (`portle`)
│   ├── cmd/portle            # CLI entrypoint
│   └── internal              # config, IPC, leader, proxy, runtime
├── packages/npm              # npm package wrapper + CLI shim
│   ├── bin/portle.js         # ESM CLI shim
│   ├── scripts/postinstall.js
│   ├── src                   # platform mapping + downloader helpers
│   └── test                  # Node tests
├── scripts/check-gofmt.sh
└── .github/workflows/ci.yml

Local development

Install deps

npm ci --ignore-scripts

Run checks

npm run lint
npm run format:check
npm run test

Run portle dev

cd go/portle
go run ./cmd/portle dev

Custom wrapped command:

go run ./cmd/portle dev -- pnpm dev

portle dev behavior

Name / port resolution order

1. CLI flags: --name, --port
2. package.json → portle.name / portle.port
3. package.json root → name / port
4. Framework first-match defaults (Next, Vite, Nuxt, SvelteKit, Astro, Remix)
5. Random free port in 3000-6000; fallback to OS ephemeral

Runtime behavior

• Spawns wrapped subprocess (npm run dev by default, or command after --)
• Injects environment variables:
  • PORT
  • PORTLE_NAME
• Connects to IPC leader (or becomes leader if none is available)
• Registers host -> {port, pid, lastSeen}
• Sends heartbeats
• Unregisters on shutdown

Leader behavior

• Owns in-memory host registry
• Hosts IPC server for register/heartbeat/unregister JSON-line messages
• Hosts reverse proxy (127.0.0.1:8080 by default)
• Routes by request Host header to localhost:<port>
• Returns 502 for unknown hosts

IPC transport

• macOS/Linux: Unix socket at /tmp/portle.sock
• Windows: named pipe at \\.\\pipe\\portle

Message types:

• register {host, port, pid}
• heartbeat {pid}
• unregister {host, pid}

npm distribution package

packages/npm contains an ESM wrapper package (portle) with:

• bin/portle.js shim that resolves and spawns the downloaded binary
• postinstall script that downloads release assets named:
  • portle-darwin-arm64
  • portle-darwin-x64
  • portle-linux-x64
  • portle-windows-x64.exe

Release URL pattern:

https://github.com/shellscape/portle/releases/download/v<version>/portle-{os}-{arch}[.exe]

Current intentional gaps

• Release publishing automation is not included here (only download-time conventions are implemented).
• Leader failover is best-effort and local-process based (no external persistence).