portcall 0.1.0 → 0.2.0

package/README.md

@@ -43,6 +43,22 @@ Node 20.19+, macOS or Linux.
 - Each command runs with `PORT` set to its service's port. `env` takes `{port}` and `{ports.<service>}`.
 - A service without `command` is external (a database in Docker, a tunnel...): portcall only checks that its port answers.
 - `cwd` runs a command in a subfolder; `readyTimeout` (seconds, default 60) bounds how long `up` waits for the port.
+- `"worktrees": true` lets each git worktree run its own servers at the same time (see below).
+
+### Git worktrees
+
+By default, every checkout of a project shares its declared ports: one checkout runs a service at a time, and the others see it as `elsewhere`.
+
+With `"worktrees": true`, each linked worktree gets its own ports. The first time portcall runs in a worktree, it picks an offset (a multiple of 10) that moves the worktree's services onto ports no known project declares and nothing listens on, and keeps it. The main checkout keeps the declared ports, and external services (a database...) keep theirs: worktrees share them.
+
+```sh
+cd ../myapp-feature-x      # git worktree add ../myapp-feature-x
+portcall up                # server on 3010, web on 5183 (offset 10)
+portcall status --json     # "port": 3010, "basePort": 3000, "worktree": "myapp-feature-x"
+portcall logs -p myapp@myapp-feature-x
+```
+
+This only works if the app takes its ports from portcall rather than hardcoding them: read `PORT` (in `vite.config`, `server: { port: Number(process.env.PORT) || 5173, strictPort: true }`), and pass the other services' URLs through `env` with `{ports.<service>}`, including proxy targets and allowed origins.
 
 ## Commands
 
@@ -56,7 +72,7 @@ Node 20.19+, macOS or Linux.
 | `portcall ports` | Every known project's ports, with conflicts. Exits 1 on a conflict. |
 | `portcall agents` | Prints a section to paste into `AGENTS.md` / `CLAUDE.md`. |
 
-Every command takes `--json`, `-p <project>` (act on a known project from anywhere) and `-C <dir>`.
+Every command takes `--json`, `-p <project>` (act on a known project from anywhere; `<project>@<worktree>` for a worktree with its own ports) and `-C <dir>`.
 
 ### Service states
 
@@ -67,7 +83,7 @@ Every command takes `--json`, `-p <project>` (act on a known project from anywhe
 | `stopped` | nothing on its port |
 | `unmanaged` | its port is held by a process started inside the project, outside portcall (say, in a terminal). `up` leaves it be; `down --force` stops it |
 | `taken` | its port is held by something outside the project. portcall never touches it |
-| `elsewhere` | portcall runs it from another checkout of the project (a git worktree) |
+| `elsewhere` | portcall runs it from another checkout of the project (a git worktree, without `"worktrees": true`) |
 
 ## With coding agents
 

package/dist/portcall.mjs

@@ -11,7 +11,7 @@ import { readlink } from "node:fs/promises";
 import { connect } from "node:net";
 import { createInterface } from "node:readline";
 // package.json
-var version$1 = "0.1.0";
+var version$1 = "0.2.0";
 // node_modules/.pnpm/zod@4.6.7/node_modules/zod/v4/core/core.js
 var _a$1;
 const _zodDesc = {
@@ -714,6 +714,7 @@ const safeParseAsync = /* @__PURE__*/ _safeParseAsync($ZodRealError);
 // node_modules/.pnpm/zod@4.6.7/node_modules/zod/v4/core/regexes.js
 const anyString = /^[\s\S]{0,}$/;
 const number$1 = /^-?\d+(?:\.\d+)?$/;
+const boolean$1 = /^(?:true|false)$/i;
 // node_modules/.pnpm/zod@4.6.7/node_modules/zod/v4/core/checks.js
 const $ZodCheck = /*@__PURE__*/ $constructor("$ZodCheck", (inst, def) => {
 	var _a;
@@ -1042,6 +1043,24 @@ const $ZodNumberFormat = /*@__PURE__*/ $constructor("$ZodNumberFormat", (inst, d
 	$ZodCheckNumberFormat.init(inst, def);
 	$ZodNumber.init(inst, def);
 });
+const $ZodBoolean = /*@__PURE__*/ $constructor("$ZodBoolean", (inst, def) => {
+	$ZodType.init(inst, def);
+	inst._zod.pattern = boolean$1;
+	inst._zod.parse = (payload, _ctx) => {
+		if (def.coerce) try {
+			payload.value = Boolean(payload.value);
+		} catch (_) {}
+		const input = payload.value;
+		if (typeof input === "boolean") return payload;
+		payload.issues.push({
+			expected: "boolean",
+			code: "invalid_type",
+			input,
+			inst
+		});
+		return payload;
+	};
+});
 const $ZodNever = /*@__PURE__*/ $constructor("$ZodNever", (inst, def) => {
 	$ZodType.init(inst, def);
 	inst._zod.parse = (payload, _ctx) => {
@@ -1441,6 +1460,13 @@ function _int(Class, params) {
 	});
 }
 // @__NO_SIDE_EFFECTS__
+function _boolean(Class, params) {
+	return new Class({
+		type: "boolean",
+		...normalizeParams(params)
+	});
+}
+// @__NO_SIDE_EFFECTS__
 function _never(Class, params) {
 	return new Class({
 		type: "never",
@@ -1581,6 +1607,14 @@ const ZodMiniNumberFormat = /*@__PURE__*/ $constructor("ZodMiniNumberFormat", (i
 function int(params) {
 	return /* @__PURE__ */ _int(ZodMiniNumberFormat, params);
 }
+const ZodMiniBoolean = /*@__PURE__*/ $constructor("ZodMiniBoolean", (inst, def) => {
+	$ZodBoolean.init(inst, def);
+	ZodMiniType.init(inst, def);
+});
+// @__NO_SIDE_EFFECTS__
+function boolean(params) {
+	return /* @__PURE__ */ _boolean(ZodMiniBoolean, params);
+}
 const ZodMiniNever = /*@__PURE__*/ $constructor("ZodMiniNever", (inst, def) => {
 	$ZodNever.init(inst, def);
 	ZodMiniType.init(inst, def);
@@ -1649,7 +1683,8 @@ const serviceSchema = /* @__PURE__ */ strictObject({
 const configSchema = /* @__PURE__ */ strictObject({
 	$schema: /* @__PURE__ */ optional(/* @__PURE__ */ string()),
 	name: nameSchema.check(describe$1("Project name, used by `portcall -p <name>` and in the logs folder.")),
-	services: (/* @__PURE__ */ record(nameSchema, serviceSchema)).check(describe$1("The project's services, by name."))
+	services: (/* @__PURE__ */ record(nameSchema, serviceSchema)).check(describe$1("The project's services, by name.")),
+	worktrees: (/* @__PURE__ */ optional(/* @__PURE__ */ boolean())).check(describe$1("Let each git worktree of the project run its services at the same time, on ports offset from the declared ones (external services keep theirs). Commands must take their port from PORT and {ports.<service>}. Default: false, all checkouts share the declared ports."))
 });
 var ConfigError = class extends Error {};
 function findConfig(from) {
@@ -1662,16 +1697,37 @@ function findConfig(from) {
 		dir = parent;
 	}
 }
-function loadProject(file) {
+/** The worktree name when `dir` is inside a linked git worktree (not the main checkout). */
+function linkedWorktree(dir) {
+	for (let current = resolve(dir);;) {
+		const dotGit = join(current, ".git");
+		if (existsSync(dotGit)) {
+			let content;
+			try {
+				content = readFileSync(dotGit, "utf8");
+			} catch {
+				return;
+			}
+			const gitDir = /^gitdir: (.+)$/m.exec(content)?.[1]?.trim();
+			if (!gitDir) return void 0;
+			const resolved = resolve(current, gitDir);
+			return existsSync(join(resolved, "commondir")) ? basename(resolved) : void 0;
+		}
+		const parent = dirname(current);
+		if (parent === current) return void 0;
+		current = parent;
+	}
+}
+function loadProject(file, offsets = {}) {
 	let raw;
 	try {
 		raw = JSON.parse(readFileSync(file, "utf8"));
 	} catch (error) {
 		throw new ConfigError(`${file}: ${error.message}`);
 	}
-	return parseProject(raw, join(realpathSync(dirname(file)), basename(file)));
+	return parseProject(raw, join(realpathSync(dirname(file)), basename(file)), offsets);
 }
-function parseProject(raw, file) {
+function parseProject(raw, file, offsets = {}) {
 	const parsed = configSchema.safeParse(raw);
 	if (!parsed.success) throw new ConfigError(`${file}:\n${prettifyError(parsed.error)}`);
 	const config = parsed.data;
@@ -1684,24 +1740,33 @@ function parseProject(raw, file) {
 		if (other) throw new ConfigError(`${file}: services "${other}" and "${name}" both use port ${service.port}`);
 		ports.set(service.port, name);
 	}
+	const worktree = config.worktrees ? linkedWorktree(root) : void 0;
+	const portOffset = worktree ? offsets[root] : void 0;
+	const effective = new Map(entries.map(([name, service]) => [name, service.port + (service.command ? portOffset ?? 0 : 0)]));
 	const services = entries.map(([name, service]) => ({
 		name,
-		port: service.port,
+		port: effective.get(name),
+		basePort: service.port,
 		command: service.command,
 		cwd: resolve(root, service.cwd ?? "."),
-		env: expandEnv(service.env ?? {}, service.port, ports, file, name),
+		env: expandEnv(service.env ?? {}, effective.get(name), effective, file, name),
 		readyTimeout: service.readyTimeout ?? DEFAULT_READY_TIMEOUT
 	}));
+	const instance = worktree ? `${config.name}@${worktree}` : config.name;
 	return {
 		name: config.name,
+		instance,
 		root,
 		file,
-		services
+		services,
+		...worktree ? {
+			worktree,
+			portOffset
+		} : {}
 	};
 }
 /** Fills `{port}` (this service) and `{ports.<service>}` (any service of the project). */
-function expandEnv(env, port, ports, file, service) {
-	const byName = new Map([...ports].map(([p, name]) => [name, p]));
+function expandEnv(env, port, byName, file, service) {
 	const out = {};
 	for (const [key, value] of Object.entries(env)) out[key] = value.replace(/\{(port|ports\.([\w.-]+))\}/g, (_, whole, other) => {
 		if (whole === "port") return String(port);
@@ -2008,12 +2073,13 @@ function knownProjects() {
 	const errors = [];
 	const kept = [];
 	const roots = readRoots();
+	const offsets = readState().offsets;
 	for (const root of roots) {
 		const file = join(root, CONFIG_FILE);
 		if (!existsSync(file)) continue;
 		kept.push(root);
 		try {
-			projects.push(loadProject(file));
+			projects.push(loadProject(file, offsets));
 		} catch (error) {
 			errors.push(error.message);
 		}
@@ -2033,10 +2099,12 @@ async function serviceStatus(project, service, state) {
 		project: project.name,
 		service: service.name,
 		port: service.port,
+		...service.port !== service.basePort ? { basePort: service.basePort } : {},
+		...project.worktree ? { worktree: project.worktree } : {},
 		url: `http://localhost:${service.port}`,
 		external: !service.command
 	};
-	const record = state.services[recordKey(project.name, service.name)];
+	const record = state.services[recordKey(project.instance, service.name)];
 	if (record) {
 		const alive = isAlive(record.supervisorPid) || isAlive(record.childPid);
 		const managed = {
@@ -2063,7 +2131,7 @@ async function serviceStatus(project, service, state) {
 			state: await isListening(service.port) ? "running" : "starting"
 		};
 	}
-	const log = service.command ? logPath(project.name, service.name) : void 0;
+	const log = service.command ? logPath(project.instance, service.name) : void 0;
 	if (!await isListening(service.port)) return {
 		...base,
 		log,
@@ -2085,22 +2153,52 @@ async function serviceStatus(project, service, state) {
 async function projectStatus(project, state, only) {
 	return Promise.all((only ?? project.services).map((service) => serviceStatus(project, service, state)));
 }
+// src/worktrees.ts
+const OFFSET_STEP = 10;
+const MAX_TRIES = 100;
+/**
+* Gives a worktree of a `worktrees: true` project its port offset the first time portcall meets it:
+* the first multiple of 10 that moves its services onto ports no known project declares and nothing listens on.
+*/
+async function withPortOffset(project) {
+	if (!project.worktree || project.portOffset !== void 0) return project;
+	const claimed = new Set(knownProjects().projects.filter((p) => p.root !== project.root).flatMap((p) => p.services.map((s) => s.port)));
+	for (const service of project.services) claimed.add(service.basePort);
+	const runnable = project.services.filter((s) => s.command);
+	let chosen;
+	for (let i = 1; i <= MAX_TRIES && chosen === void 0; i++) {
+		const offset = i * OFFSET_STEP;
+		const ports = runnable.map((s) => s.basePort + offset);
+		if (ports.some((port) => port > 65535)) break;
+		if (ports.some((port) => claimed.has(port))) continue;
+		if (!(await Promise.all(ports.map((port) => isListening(port)))).some(Boolean)) chosen = offset;
+	}
+	if (chosen === void 0) throw new Error(`no free port offset for ${project.instance}: every candidate port is declared or in use`);
+	await updateState((state) => {
+		const offsets = state.offsets ??= {};
+		for (const root of Object.keys(offsets)) if (!existsSync(join(root, "portcall.json"))) delete offsets[root];
+		offsets[project.root] ??= chosen;
+	});
+	return loadProject(project.file, readState().offsets);
+}
 // src/commands.ts
 const SUPERVISE_COMMAND = "__supervise";
 const STOP_WAIT_MS = 8e3;
 var UsageError = class extends Error {};
-function resolveProject(cwd, name) {
+/** `name` is a project name, or `name@worktree` for a worktree with its own ports. */
+async function resolveProject(cwd, name) {
 	if (name) {
 		const { projects } = knownProjects();
-		const matches = projects.filter((project) => project.name === name);
+		const exact = projects.filter((project) => project.instance === name);
+		const matches = exact.length ? exact : projects.filter((project) => project.name === name);
 		if (matches.length === 0) throw new UsageError(`unknown project "${name}": run any portcall command once inside it so portcall knows where it is`);
 		const here = matches.find((project) => cwd === project.root || cwd.startsWith(`${project.root}/`));
-		if (here || matches.length === 1) return here ?? matches[0];
-		throw new UsageError(`"${name}" exists in several checkouts, run portcall from the one you want:\n${matches.map((p) => `  ${p.root}`).join("\n")}`);
+		if (here || matches.length === 1) return withPortOffset(here ?? matches[0]);
+		throw new UsageError(`"${name}" exists in several checkouts, run portcall from the one you want${matches.some((p) => p.worktree) ? " or name it as project@worktree" : ""}:\n${matches.map((p) => `  ${p.instance}  ${p.root}`).join("\n")}`);
 	}
 	const file = findConfig(cwd);
 	if (!file) throw new ConfigError(`no portcall.json in ${cwd} or above (see \`portcall help\`)`);
-	const project = loadProject(file);
+	const project = await withPortOffset(loadProject(file, readState().offsets));
 	rememberProject(project.root);
 	return project;
 }
@@ -2113,6 +2211,12 @@ function selectServices(project, names, runnableOnly = false) {
 		return service;
 	});
 }
+function worktreeFields(project) {
+	return project.worktree ? {
+		worktree: project.worktree,
+		portOffset: project.portOffset
+	} : {};
+}
 function table(rows) {
 	const widths = rows[0].map((_, i) => Math.max(...rows.map((row) => row[i].length)));
 	return rows.map((row) => row.map((cell, i) => cell.padEnd(widths[i])).join("  ").trimEnd()).join("\n");
@@ -2148,7 +2252,7 @@ function statusRows(statuses, withProject) {
 	];
 	const now = Date.now();
 	return [head, ...statuses.map((s) => [
-		...withProject ? [s.project] : [],
+		...withProject ? [s.worktree ? `${s.project}@${s.worktree}` : s.project] : [],
 		s.service,
 		s.state,
 		String(s.port),
@@ -2172,10 +2276,11 @@ async function status(io, cwd, opts) {
 		}
 		return 0;
 	}
-	const project = resolveProject(cwd, opts.project);
+	const project = await resolveProject(cwd, opts.project);
 	const statuses = await projectStatus(project, state);
 	io.out(io.json ? JSON.stringify({
 		project: project.name,
+		...worktreeFields(project),
 		root: project.root,
 		services: statuses
 	}, null, 2) : table(statusRows(statuses, false)));
@@ -2187,9 +2292,9 @@ const UP_FAILURES = [
 	"blocked"
 ];
 function startService(project, service, state) {
-	const log = logPath(project.name, service.name);
+	const log = logPath(project.instance, service.name);
 	const spec = {
-		project: project.name,
+		project: project.instance,
 		service: service.name,
 		command: service.command,
 		cwd: service.cwd,
@@ -2215,8 +2320,8 @@ function startService(project, service, state) {
 		exited = true;
 	});
 	child.unref();
-	state.services[recordKey(project.name, service.name)] = {
-		project: project.name,
+	state.services[recordKey(project.instance, service.name)] = {
+		project: project.instance,
 		service: service.name,
 		root: project.root,
 		port: service.port,
@@ -2240,7 +2345,7 @@ async function waitReady(service, exited) {
 	}
 }
 async function up(io, cwd, names, opts) {
-	const project = resolveProject(cwd, opts.project);
+	const project = await resolveProject(cwd, opts.project);
 	const services = selectServices(project, names);
 	const statuses = await projectStatus(project, readState(), services);
 	const results = [];
@@ -2309,9 +2414,9 @@ async function up(io, cwd, names, opts) {
 			outcome: "started",
 			detail: `ready in ${((Date.now() - t0) / 1e3).toFixed(1)}s`
 		};
-		const logTail = readLog(logPath(project.name, service.name), service.name).slice(-30).map((l) => formatLine(l));
+		const logTail = readLog(logPath(project.instance, service.name), service.name).slice(-30).map((l) => formatLine(l));
 		if (ready === "exited") {
-			const record = readState().services[recordKey(project.name, service.name)];
+			const record = readState().services[recordKey(project.instance, service.name)];
 			return {
 				...base,
 				outcome: "crashed",
@@ -2331,6 +2436,7 @@ async function up(io, cwd, names, opts) {
 	const failed = results.some((r) => UP_FAILURES.includes(r.outcome));
 	if (io.json) io.out(JSON.stringify({
 		project: project.name,
+		...worktreeFields(project),
 		ok: !failed,
 		services: results
 	}, null, 2));
@@ -2371,12 +2477,12 @@ async function stopPid(pid) {
 	if (!await waitForDeath(pid, STOP_WAIT_MS)) signal(pid, "SIGKILL");
 }
 async function down(io, cwd, names, opts) {
-	const project = resolveProject(cwd, opts.project);
+	const project = await resolveProject(cwd, opts.project);
 	const services = selectServices(project, names);
 	const state = readState();
 	const statuses = await projectStatus(project, state, services);
 	const results = await Promise.all(statuses.map(async (st) => {
-		const record = state.services[recordKey(project.name, st.service)];
+		const record = state.services[recordKey(project.instance, st.service)];
 		if (st.external) return {
 			service: st.service,
 			outcome: "skipped",
@@ -2444,7 +2550,7 @@ async function down(io, cwd, names, opts) {
 	return 0;
 }
 async function restart(io, cwd, names, opts) {
-	const runnable = selectServices(resolveProject(cwd, opts.project), names, true).map((s) => s.name);
+	const runnable = selectServices(await resolveProject(cwd, opts.project), names, true).map((s) => s.name);
 	await down(io, cwd, runnable, {
 		...opts,
 		quiet: true
@@ -2452,10 +2558,10 @@ async function restart(io, cwd, names, opts) {
 	return up(io, cwd, runnable, opts);
 }
 async function logs(io, cwd, names, opts) {
-	const project = resolveProject(cwd, opts.project);
+	const project = await resolveProject(cwd, opts.project);
 	const services = selectServices(project, names, true);
 	const files = services.map((s) => ({
-		file: logPath(project.name, s.name),
+		file: logPath(project.instance, s.name),
 		service: s.name
 	}));
 	const width = services.length > 1 ? Math.max(...services.map((s) => s.name.length)) : 0;
@@ -2476,19 +2582,20 @@ async function logs(io, cwd, names, opts) {
 	return 0;
 }
 async function ports(io, cwd) {
-	const file = findConfig(cwd);
-	if (file) rememberProject(loadProject(file).root);
+	if (findConfig(cwd)) await resolveProject(cwd);
 	const { projects, errors } = knownProjects();
 	const state = readState();
+	const claimant = (project, service) => service.command ? project.instance : project.name;
 	const claims = /* @__PURE__ */ new Map();
-	for (const project of projects) for (const service of project.services) claims.set(service.port, (claims.get(service.port) ?? /* @__PURE__ */ new Set()).add(project.name));
+	for (const project of projects) for (const service of project.services) claims.set(service.port, (claims.get(service.port) ?? /* @__PURE__ */ new Set()).add(claimant(project, service)));
 	const seen = /* @__PURE__ */ new Set();
 	const rows = [];
 	for (const project of projects) {
-		if (seen.has(project.name)) continue;
-		seen.add(project.name);
-		for (const st of await projectStatus(project, state)) {
-			const others = [...claims.get(st.port)].filter((name) => name !== project.name);
+		if (seen.has(project.instance)) continue;
+		seen.add(project.instance);
+		for (const [i, st] of (await projectStatus(project, state)).entries()) {
+			const own = claimant(project, project.services[i]);
+			const others = [...claims.get(st.port)].filter((name) => name !== own);
 			rows.push({
 				...st,
 				conflict: others
@@ -2509,7 +2616,7 @@ async function ports(io, cwd) {
 			"INFO"
 		], ...rows.map((r) => [
 			String(r.port),
-			r.project,
+			r.worktree ? `${r.project}@${r.worktree}` : r.project,
 			r.service,
 			r.state,
 			[r.conflict.length ? `CONFLICT with ${r.conflict.join(", ")}` : "", describe(r)].filter(Boolean).join("; ")
@@ -2632,7 +2739,8 @@ Usage:
   portcall agents                 Print an AGENTS.md section telling coding agents how to use portcall
 
 Options:
-  -p, --project <name>  Act on a known project from anywhere (default: the portcall.json at or above the cwd)
+  -p, --project <name>  Act on a known project from anywhere (default: the portcall.json at or above the cwd);
+                        <name>@<worktree> for a git worktree with its own ports
   -C, --cwd <dir>       Run as if started in <dir>
       --json            Machine-readable output
       --no-wait         up/restart: return without waiting for the port
@@ -2658,6 +2766,7 @@ portcall.json, at the project root:
   }
   A service without "command" is external (a database in Docker...): portcall only checks its port.
   Each command gets PORT set to its port. Logs and state live in ~/.portcall (PORTCALL_HOME).
+  "worktrees": true gives each git worktree its own ports (declared + an offset), so they run at once.
 `;
 async function main(argv) {
 	if (argv[0] === "__supervise") {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "portcall",
   "type": "module",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Run your local dev servers in the background, on fixed ports, with logs your coding agents can read",
   "author": "Joris Gallot",
   "license": "MIT",

package/schema.json

@@ -56,6 +56,10 @@
         "additionalProperties": false
       },
       "description": "The project's services, by name."
+    },
+    "worktrees": {
+      "description": "Let each git worktree of the project run its services at the same time, on ports offset from the declared ones (external services keep theirs). Commands must take their port from PORT and {ports.<service>}. Default: false, all checkouts share the declared ports.",
+      "type": "boolean"
     }
   },
   "required": [