@ree-auz/nook 0.1.0 → 0.1.2

package/src/names.mjs

@@ -1,65 +1,65 @@
-import { NookError } from "./errors.mjs";
-
-export const SUBCOMMANDS = ["init", "ls", "rm", "clean", "hooks", "forget", "doctor", "help", "version"];
-
-/**
- * Workspace name = branch name = folder name.
- * Lowercase letters, digits, "-" and "."; no "/"; not a subcommand.
- * Returns an error message, or null when the name is valid.
- */
-export function nameProblem(name) {
-  if (typeof name !== "string" || name === "") return "name is empty";
-  if (name.length > 100) return "name is longer than 100 characters";
-  if (name.includes("/")) return `"${name}" contains "/"; use "-" instead`;
-  if (!/^[a-z0-9.-]+$/.test(name))
-    return `"${name}" may only use lowercase letters, digits, "-" and "."`;
-  if (!/^[a-z0-9]/.test(name)) return `"${name}" must start with a letter or digit`;
-  if (name.endsWith(".") || name.endsWith(".lock"))
-    return `"${name}" cannot end with "." or ".lock"`;
-  if (name.includes("..")) return `"${name}" cannot contain ".."`;
-  if (SUBCOMMANDS.includes(name)) return `"${name}" is a nk command; pick another name`;
-  return null;
-}
-
-export function assertName(name, what = "workspace") {
-  const problem = nameProblem(name);
-  if (problem) throw new NookError(`Invalid ${what} name: ${problem}`);
-  return name;
-}
-
-/**
- * Turns any branch-like text into a valid name, so callers (trackers, scripts,
- * people) can pass what they have: lowercase it, turn "/", spaces, non-ASCII
- * and other characters into "-", and tidy the ends.
- * "REE-267-Nook-第-1-步：建-nook" -> "ree-267-nook-1-nook"; "feat/Login" -> "feat-login".
- */
-export function normalizeName(input) {
-  return String(input)
-    .toLowerCase()
-    .replace(/[^a-z0-9.-]+/g, "-")
-    .replace(/\.{2,}/g, ".")
-    .replace(/-{2,}/g, "-")
-    .replace(/^[^a-z0-9]+/, "")
-    .replace(/(\.lock)+$/, "")
-    .replace(/[.-]+$/, "")
-    .slice(0, 100)
-    .replace(/[.-]+$/, "");
-}
-
-/** Normalizes, then checks what normalizing cannot fix (empty, command names). */
-export function toName(input) {
-  const name = normalizeName(input);
-  const problem = nameProblem(name);
-  if (problem) throw new NookError(`Cannot use "${input}" as a workspace name: ${problem}`);
-  return name;
-}
-
-/** Turns a folder name into a repository short name suggestion. */
-export function suggestRepoName(folder) {
-  const name = folder
-    .toLowerCase()
-    .replace(/[^a-z0-9.-]+/g, "-")
-    .replace(/^[^a-z0-9]+/, "")
-    .replace(/[.-]+$/, "");
-  return nameProblem(name) ? "repo" : name;
-}
+import { NookError } from "./errors.mjs";
+
+export const SUBCOMMANDS = ["init", "ls", "rm", "clean", "hooks", "forget", "doctor", "help", "version"];
+
+/**
+ * Workspace name = branch name = folder name.
+ * Lowercase letters, digits, "-" and "."; no "/"; not a subcommand.
+ * Returns an error message, or null when the name is valid.
+ */
+export function nameProblem(name) {
+  if (typeof name !== "string" || name === "") return "name is empty";
+  if (name.length > 100) return "name is longer than 100 characters";
+  if (name.includes("/")) return `"${name}" contains "/"; use "-" instead`;
+  if (!/^[a-z0-9.-]+$/.test(name))
+    return `"${name}" may only use lowercase letters, digits, "-" and "."`;
+  if (!/^[a-z0-9]/.test(name)) return `"${name}" must start with a letter or digit`;
+  if (name.endsWith(".") || name.endsWith(".lock"))
+    return `"${name}" cannot end with "." or ".lock"`;
+  if (name.includes("..")) return `"${name}" cannot contain ".."`;
+  if (SUBCOMMANDS.includes(name)) return `"${name}" is a nk command; pick another name`;
+  return null;
+}
+
+export function assertName(name, what = "workspace") {
+  const problem = nameProblem(name);
+  if (problem) throw new NookError(`Invalid ${what} name: ${problem}`);
+  return name;
+}
+
+/**
+ * Turns any branch-like text into a valid name, so callers (trackers, scripts,
+ * people) can pass what they have: lowercase it, turn "/", spaces, non-ASCII
+ * and other characters into "-", and tidy the ends.
+ * "REE-267-Nook-第-1-步：建-nook" -> "ree-267-nook-1-nook"; "feat/Login" -> "feat-login".
+ */
+export function normalizeName(input) {
+  return String(input)
+    .toLowerCase()
+    .replace(/[^a-z0-9.-]+/g, "-")
+    .replace(/\.{2,}/g, ".")
+    .replace(/-{2,}/g, "-")
+    .replace(/^[^a-z0-9]+/, "")
+    .replace(/(\.lock)+$/, "")
+    .replace(/[.-]+$/, "")
+    .slice(0, 100)
+    .replace(/[.-]+$/, "");
+}
+
+/** Normalizes, then checks what normalizing cannot fix (empty, command names). */
+export function toName(input) {
+  const name = normalizeName(input);
+  const problem = nameProblem(name);
+  if (problem) throw new NookError(`Cannot use "${input}" as a workspace name: ${problem}`);
+  return name;
+}
+
+/** Turns a folder name into a repository short name suggestion. */
+export function suggestRepoName(folder) {
+  const name = folder
+    .toLowerCase()
+    .replace(/[^a-z0-9.-]+/g, "-")
+    .replace(/^[^a-z0-9]+/, "")
+    .replace(/[.-]+$/, "");
+  return nameProblem(name) ? "repo" : name;
+}

package/src/occupancy-windows.ps1

@@ -1,59 +1,59 @@
-# Lists processes whose current directory is inside -Root.
-# Prints JSON: { processes: [{ pid, name, reasons }], inaccessible }.
-param([Parameter(Mandatory = $true)][string]$Root)
-$ErrorActionPreference = 'Stop'
-if ([Runtime.InteropServices.RuntimeInformation]::ProcessArchitecture -ne 'X64') { throw 'Windows x64 is required for the process scan' }
-Add-Type -TypeDefinition @'
-using System;
-using System.Collections.Generic;
-using System.Diagnostics;
-using System.IO;
-using System.Runtime.InteropServices;
-namespace Nook {
- public class DirectoryProcess { public int pid; public string name; }
- public class DirectoryScan { public DirectoryProcess[] processes; public int inaccessible; }
- public static class DirectoryInspector {
-  [DllImport("kernel32.dll")] static extern IntPtr OpenProcess(uint access, bool inherit, int pid);
-  [DllImport("kernel32.dll")] static extern bool CloseHandle(IntPtr handle);
-  [DllImport("kernel32.dll")] static extern bool ReadProcessMemory(IntPtr process, IntPtr address, byte[] buffer, IntPtr size, out IntPtr read);
-  [DllImport("kernel32.dll")] static extern bool IsWow64Process(IntPtr process, out bool wow64);
-  [DllImport("ntdll.dll")] static extern int NtQueryInformationProcess(IntPtr process, int infoClass, byte[] info, int size, out int returned);
-  static byte[] Read(IntPtr process, long address, int size) {
-   byte[] data = new byte[size]; IntPtr read;
-   if (!ReadProcessMemory(process, new IntPtr(address), data, new IntPtr(size), out read) || read.ToInt64() != size) throw new InvalidOperationException();
-   return data;
-  }
-  public static DirectoryScan Scan(string root) {
-   string target = Path.GetFullPath(root).TrimEnd('\\');
-   var found = new List<DirectoryProcess>(); int unavailable = 0;
-   foreach (Process process in Process.GetProcesses()) {
-    using (process) {
-     IntPtr handle = OpenProcess(0x410, false, process.Id);
-     if (handle == IntPtr.Zero) { unavailable++; continue; }
-     try {
-      bool wow64;
-      if (!IsWow64Process(handle, out wow64) || wow64) { unavailable++; continue; }
-      byte[] info = new byte[48]; int returned;
-      if (NtQueryInformationProcess(handle, 0, info, info.Length, out returned) != 0) { unavailable++; continue; }
-      long peb = BitConverter.ToInt64(info, 8);
-      long parameters = BitConverter.ToInt64(Read(handle, peb + 0x20, 8), 0);
-      // 64-bit RTL_USER_PROCESS_PARAMETERS.CurrentDirectory.DosPath.
-      byte[] current = Read(handle, parameters + 0x38, 16);
-      int length = BitConverter.ToUInt16(current, 0);
-      if (length == 0 || length > 32766 || length % 2 != 0) continue;
-      string cwd = System.Text.Encoding.Unicode.GetString(Read(handle, BitConverter.ToInt64(current, 8), length)).TrimEnd('\\');
-      if (cwd.StartsWith(@"\\?\", StringComparison.Ordinal)) cwd = cwd.Substring(4);
-      if (cwd.Equals(target, StringComparison.OrdinalIgnoreCase) || cwd.StartsWith(target + "\\", StringComparison.OrdinalIgnoreCase))
-       found.Add(new DirectoryProcess { pid = process.Id, name = process.ProcessName });
-     } catch { unavailable++; }
-     finally { CloseHandle(handle); }
-    }
-   }
-   return new DirectoryScan { processes = found.ToArray(), inaccessible = unavailable };
-  }
- }
-}
-'@
-$scan = [Nook.DirectoryInspector]::Scan($Root)
-$processes = @($scan.processes | ForEach-Object { [ordered]@{ pid = $_.pid; name = $_.name; reasons = @('working directory') } })
-[pscustomobject]@{ processes = $processes; inaccessible = $scan.inaccessible } | ConvertTo-Json -Depth 5 -Compress
+# Lists processes whose current directory is inside -Root.
+# Prints JSON: { processes: [{ pid, name, reasons }], inaccessible }.
+param([Parameter(Mandatory = $true)][string]$Root)
+$ErrorActionPreference = 'Stop'
+if ([Runtime.InteropServices.RuntimeInformation]::ProcessArchitecture -ne 'X64') { throw 'Windows x64 is required for the process scan' }
+Add-Type -TypeDefinition @'
+using System;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.IO;
+using System.Runtime.InteropServices;
+namespace Nook {
+ public class DirectoryProcess { public int pid; public string name; }
+ public class DirectoryScan { public DirectoryProcess[] processes; public int inaccessible; }
+ public static class DirectoryInspector {
+  [DllImport("kernel32.dll")] static extern IntPtr OpenProcess(uint access, bool inherit, int pid);
+  [DllImport("kernel32.dll")] static extern bool CloseHandle(IntPtr handle);
+  [DllImport("kernel32.dll")] static extern bool ReadProcessMemory(IntPtr process, IntPtr address, byte[] buffer, IntPtr size, out IntPtr read);
+  [DllImport("kernel32.dll")] static extern bool IsWow64Process(IntPtr process, out bool wow64);
+  [DllImport("ntdll.dll")] static extern int NtQueryInformationProcess(IntPtr process, int infoClass, byte[] info, int size, out int returned);
+  static byte[] Read(IntPtr process, long address, int size) {
+   byte[] data = new byte[size]; IntPtr read;
+   if (!ReadProcessMemory(process, new IntPtr(address), data, new IntPtr(size), out read) || read.ToInt64() != size) throw new InvalidOperationException();
+   return data;
+  }
+  public static DirectoryScan Scan(string root) {
+   string target = Path.GetFullPath(root).TrimEnd('\\');
+   var found = new List<DirectoryProcess>(); int unavailable = 0;
+   foreach (Process process in Process.GetProcesses()) {
+    using (process) {
+     IntPtr handle = OpenProcess(0x410, false, process.Id);
+     if (handle == IntPtr.Zero) { unavailable++; continue; }
+     try {
+      bool wow64;
+      if (!IsWow64Process(handle, out wow64) || wow64) { unavailable++; continue; }
+      byte[] info = new byte[48]; int returned;
+      if (NtQueryInformationProcess(handle, 0, info, info.Length, out returned) != 0) { unavailable++; continue; }
+      long peb = BitConverter.ToInt64(info, 8);
+      long parameters = BitConverter.ToInt64(Read(handle, peb + 0x20, 8), 0);
+      // 64-bit RTL_USER_PROCESS_PARAMETERS.CurrentDirectory.DosPath.
+      byte[] current = Read(handle, parameters + 0x38, 16);
+      int length = BitConverter.ToUInt16(current, 0);
+      if (length == 0 || length > 32766 || length % 2 != 0) continue;
+      string cwd = System.Text.Encoding.Unicode.GetString(Read(handle, BitConverter.ToInt64(current, 8), length)).TrimEnd('\\');
+      if (cwd.StartsWith(@"\\?\", StringComparison.Ordinal)) cwd = cwd.Substring(4);
+      if (cwd.Equals(target, StringComparison.OrdinalIgnoreCase) || cwd.StartsWith(target + "\\", StringComparison.OrdinalIgnoreCase))
+       found.Add(new DirectoryProcess { pid = process.Id, name = process.ProcessName });
+     } catch { unavailable++; }
+     finally { CloseHandle(handle); }
+    }
+   }
+   return new DirectoryScan { processes = found.ToArray(), inaccessible = unavailable };
+  }
+ }
+}
+'@
+$scan = [Nook.DirectoryInspector]::Scan($Root)
+$processes = @($scan.processes | ForEach-Object { [ordered]@{ pid = $_.pid; name = $_.name; reasons = @('working directory') } })
+[pscustomobject]@{ processes = $processes; inaccessible = $scan.inaccessible } | ConvertTo-Json -Depth 5 -Compress

package/src/occupancy.mjs

@@ -1,131 +1,131 @@
-import { spawnSync } from "node:child_process";
-import { readdirSync, readlinkSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { which } from "./agents.mjs";
-import { isInside, realPath } from "./home.mjs";
-
-function add(found, pid, name, reason) {
-  const current = found.get(pid);
-  if (current) {
-    if (!current.reasons.includes(reason)) current.reasons.push(reason);
-  } else found.set(pid, { pid, name, reasons: [reason] });
-}
-
-function linuxScan(root) {
-  const found = new Map();
-  let inaccessible = 0;
-  for (const entry of readdirSync("/proc")) {
-    if (!/^\d+$/.test(entry)) continue;
-    const pid = Number(entry);
-    if (pid === process.pid) continue;
-    let name = entry;
-    try {
-      name = readlinkSync(`/proc/${entry}/exe`).split("/").pop();
-    } catch {
-      /* Name is best effort. */
-    }
-    try {
-      if (isInside(readlinkSync(`/proc/${entry}/cwd`), root, "linux")) add(found, pid, name, "working directory");
-    } catch {
-      inaccessible++;
-    }
-  }
-  return { processes: [...found.values()], inaccessible };
-}
-
-/** Parses `lsof -d cwd -F pcfn` output and keeps working directories below `root`. */
-export function parseLsof(text, root, platform = "darwin") {
-  const found = new Map();
-  let pid = 0;
-  let name = "";
-  let fd = "";
-  for (const line of text.split(/\r?\n/)) {
-    const tag = line[0];
-    const value = line.slice(1);
-    if (tag === "p") {
-      pid = Number(value);
-      name = "";
-    } else if (tag === "c") name = value;
-    else if (tag === "f") fd = value;
-    else if (tag === "n" && pid && pid !== process.pid && value.startsWith("/") && isInside(value, root, platform))
-      fd === "cwd" && add(found, pid, name || String(pid), "working directory");
-  }
-  return [...found.values()];
-}
-
-function lsofScan(root, platform) {
-  const lsof = which("lsof") ?? (["/usr/sbin/lsof", "/usr/bin/lsof"].find((p) => which(p)) || null);
-  if (!lsof) return { processes: [], unsupported: "lsof not found" };
-  const result = spawnSync(lsof, ["-n", "-P", "-w", "-d", "cwd", "-F", "pcfn"], { encoding: "utf8", maxBuffer: 512 * 1024 * 1024 });
-  if (result.error) return { processes: [], unsupported: result.error.message };
-  return { processes: parseLsof(result.stdout, root, platform) };
-}
-
-function windowsScan(root) {
-  const script = fileURLToPath(new URL("./occupancy-windows.ps1", import.meta.url));
-  const shell = which("pwsh") ?? "powershell.exe";
-  const result = spawnSync(shell, ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-File", script, "-Root", root], {
-    encoding: "utf8",
-    maxBuffer: 64 * 1024 * 1024,
-    windowsHide: true,
-  });
-  if (result.error || result.status !== 0)
-    return { processes: [], unsupported: (result.stderr || result.error?.message || "scan failed").trim().split(/\r?\n/)[0] };
-  const data = JSON.parse(result.stdout);
-  const list = Array.isArray(data.processes) ? data.processes : data.processes ? [data.processes] : [];
-  return {
-    processes: list.filter((item) => item.pid !== process.pid).map((item) => ({ pid: item.pid, name: item.name, reasons: [].concat(item.reasons) })),
-    inaccessible: data.inaccessible,
-  };
-}
-
-/**
- * Processes whose working directory is inside `root`: terminals, dev servers
- * and agents started there. Like worktrunk's `--reap`, open files are not
- * scanned: that is slow and editors usually keep their directory elsewhere.
- */
-export function findOccupants(root, platform = process.platform) {
-  const target = realPath(root);
-  if (platform === "linux") return linuxScan(target);
-  if (platform === "win32") return windowsScan(target);
-  return lsofScan(target, platform);
-}
-
-export function describeOccupants(processes) {
-  return processes.map((item) => `  ${item.name} (PID ${item.pid}): ${item.reasons.join(", ")}`).join("\n");
-}
-
-/**
- * Ends the processes and their children. Windows uses taskkill /T /F; macOS and
- * Linux send SIGTERM, then SIGKILL to what is still running after 3 seconds.
- */
-export async function stopProcesses(processes, platform = process.platform) {
-  if (platform === "win32") {
-    for (const { pid } of processes) spawnSync("taskkill", ["/PID", String(pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
-    return;
-  }
-  const alive = (pid) => {
-    try {
-      process.kill(pid, 0);
-      return true;
-    } catch {
-      return false;
-    }
-  };
-  for (const { pid } of processes) {
-    try {
-      process.kill(pid, "SIGTERM");
-    } catch {
-      /* Already gone. */
-    }
-  }
-  for (let waited = 0; waited < 3000 && processes.some(({ pid }) => alive(pid)); waited += 100)
-    await new Promise((done) => setTimeout(done, 100));
-  for (const { pid } of processes) {
-    try {
-      process.kill(pid, "SIGKILL");
-    } catch {
-      /* Already gone. */
-    }
-  }
-}
+import { spawnSync } from "node:child_process";
+import { readdirSync, readlinkSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { which } from "./agents.mjs";
+import { isInside, realPath } from "./home.mjs";
+
+function add(found, pid, name, reason) {
+  const current = found.get(pid);
+  if (current) {
+    if (!current.reasons.includes(reason)) current.reasons.push(reason);
+  } else found.set(pid, { pid, name, reasons: [reason] });
+}
+
+function linuxScan(root) {
+  const found = new Map();
+  let inaccessible = 0;
+  for (const entry of readdirSync("/proc")) {
+    if (!/^\d+$/.test(entry)) continue;
+    const pid = Number(entry);
+    if (pid === process.pid) continue;
+    let name = entry;
+    try {
+      name = readlinkSync(`/proc/${entry}/exe`).split("/").pop();
+    } catch {
+      /* Name is best effort. */
+    }
+    try {
+      if (isInside(readlinkSync(`/proc/${entry}/cwd`), root, "linux")) add(found, pid, name, "working directory");
+    } catch {
+      inaccessible++;
+    }
+  }
+  return { processes: [...found.values()], inaccessible };
+}
+
+/** Parses `lsof -d cwd -F pcfn` output and keeps working directories below `root`. */
+export function parseLsof(text, root, platform = "darwin") {
+  const found = new Map();
+  let pid = 0;
+  let name = "";
+  let fd = "";
+  for (const line of text.split(/\r?\n/)) {
+    const tag = line[0];
+    const value = line.slice(1);
+    if (tag === "p") {
+      pid = Number(value);
+      name = "";
+    } else if (tag === "c") name = value;
+    else if (tag === "f") fd = value;
+    else if (tag === "n" && pid && pid !== process.pid && value.startsWith("/") && isInside(value, root, platform))
+      fd === "cwd" && add(found, pid, name || String(pid), "working directory");
+  }
+  return [...found.values()];
+}
+
+function lsofScan(root, platform) {
+  const lsof = which("lsof") ?? (["/usr/sbin/lsof", "/usr/bin/lsof"].find((p) => which(p)) || null);
+  if (!lsof) return { processes: [], unsupported: "lsof not found" };
+  const result = spawnSync(lsof, ["-n", "-P", "-w", "-d", "cwd", "-F", "pcfn"], { encoding: "utf8", maxBuffer: 512 * 1024 * 1024 });
+  if (result.error) return { processes: [], unsupported: result.error.message };
+  return { processes: parseLsof(result.stdout, root, platform) };
+}
+
+function windowsScan(root) {
+  const script = fileURLToPath(new URL("./occupancy-windows.ps1", import.meta.url));
+  const shell = which("pwsh") ?? "powershell.exe";
+  const result = spawnSync(shell, ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-File", script, "-Root", root], {
+    encoding: "utf8",
+    maxBuffer: 64 * 1024 * 1024,
+    windowsHide: true,
+  });
+  if (result.error || result.status !== 0)
+    return { processes: [], unsupported: (result.stderr || result.error?.message || "scan failed").trim().split(/\r?\n/)[0] };
+  const data = JSON.parse(result.stdout);
+  const list = Array.isArray(data.processes) ? data.processes : data.processes ? [data.processes] : [];
+  return {
+    processes: list.filter((item) => item.pid !== process.pid).map((item) => ({ pid: item.pid, name: item.name, reasons: [].concat(item.reasons) })),
+    inaccessible: data.inaccessible,
+  };
+}
+
+/**
+ * Processes whose working directory is inside `root`: terminals, dev servers
+ * and agents started there. Like worktrunk's `--reap`, open files are not
+ * scanned: that is slow and editors usually keep their directory elsewhere.
+ */
+export function findOccupants(root, platform = process.platform) {
+  const target = realPath(root);
+  if (platform === "linux") return linuxScan(target);
+  if (platform === "win32") return windowsScan(target);
+  return lsofScan(target, platform);
+}
+
+export function describeOccupants(processes) {
+  return processes.map((item) => `  ${item.name} (PID ${item.pid}): ${item.reasons.join(", ")}`).join("\n");
+}
+
+/**
+ * Ends the processes and their children. Windows uses taskkill /T /F; macOS and
+ * Linux send SIGTERM, then SIGKILL to what is still running after 3 seconds.
+ */
+export async function stopProcesses(processes, platform = process.platform) {
+  if (platform === "win32") {
+    for (const { pid } of processes) spawnSync("taskkill", ["/PID", String(pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
+    return;
+  }
+  const alive = (pid) => {
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  for (const { pid } of processes) {
+    try {
+      process.kill(pid, "SIGTERM");
+    } catch {
+      /* Already gone. */
+    }
+  }
+  for (let waited = 0; waited < 3000 && processes.some(({ pid }) => alive(pid)); waited += 100)
+    await new Promise((done) => setTimeout(done, 100));
+  for (const { pid } of processes) {
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch {
+      /* Already gone. */
+    }
+  }
+}

package/src/ports.mjs

@@ -1,45 +1,89 @@
-import { createServer } from "node:net";
-import { NookError } from "./errors.mjs";
-
-export const PORT_BLOCK = 10;
-export const DEFAULT_PORT_BASE = 20000;
-const MAX_PORT = 65535;
-
-/** First ports of every workspace that already has a block. */
-export function usedPorts(config) {
-  const used = [];
-  for (const repo of Object.values(config.repos ?? {}))
-    for (const ws of Object.values(repo.workspaces ?? {}))
-      if (Number.isInteger(ws.port)) used.push(ws.port);
-  return used;
-}
-
-function overlaps(start, used) {
-  return used.some((other) => start < other + PORT_BLOCK && other < start + PORT_BLOCK);
-}
-
-export function portFree(port, host = "127.0.0.1") {
-  return new Promise((done) => {
-    const server = createServer();
-    server.once("error", () => done(false));
-    server.listen({ port, host, exclusive: true }, () => server.close(() => done(true)));
-  });
-}
-
-export async function blockFree(start, isFree = portFree) {
-  for (let port = start; port < start + PORT_BLOCK; port++) if (!(await isFree(port))) return false;
-  return true;
-}
-
-/**
- * Gives a workspace PORT_BLOCK ports in a row. Skips blocks other workspaces
- * own and blocks where something is already listening.
- */
-export async function allocatePort(config, { base = config.port_base ?? DEFAULT_PORT_BASE, isFree = portFree } = {}) {
-  const used = usedPorts(config);
-  for (let start = base; start + PORT_BLOCK - 1 <= MAX_PORT; start += PORT_BLOCK) {
-    if (overlaps(start, used)) continue;
-    if (await blockFree(start, isFree)) return start;
-  }
-  throw new NookError(`No free block of ${PORT_BLOCK} ports from ${base}`);
-}
+import { readFileSync } from "node:fs";
+import { createServer } from "node:net";
+import spawn from "cross-spawn";
+import { NookError } from "./errors.mjs";
+
+export const PORT_BLOCK = 10;
+export const DEFAULT_PORT_BASE = 20000;
+const MAX_PORT = 65535;
+
+/** First ports of every workspace that already has a block. */
+export function usedPorts(config) {
+  const used = [];
+  for (const repo of Object.values(config.repos ?? {}))
+    for (const ws of Object.values(repo.workspaces ?? {}))
+      if (Number.isInteger(ws.port)) used.push(ws.port);
+  return used;
+}
+
+function overlaps(start, used) {
+  return used.some((other) => start < other + PORT_BLOCK && other < start + PORT_BLOCK);
+}
+
+export function portFree(port, host = "127.0.0.1") {
+  return new Promise((done) => {
+    const server = createServer();
+    server.once("error", () => done(false));
+    server.listen({ port, host, exclusive: true }, () => server.close(() => done(true)));
+  });
+}
+
+export async function blockFree(start, isFree = portFree) {
+  for (let port = start; port < start + PORT_BLOCK; port++) if (!(await isFree(port))) return false;
+  return true;
+}
+
+/** Reads the start and size of Windows' dynamic port range from netsh, in any language: the last two numbers. */
+export function parseDynamicPorts(text) {
+  const numbers = String(text).match(/\d+/g)?.map(Number) ?? [];
+  if (numbers.length < 2) return null;
+  const [start, count] = numbers.slice(-2);
+  return start > 0 && count > 0 ? { start, end: Math.min(start + count - 1, MAX_PORT) } : null;
+}
+
+let cachedRange;
+/**
+ * The ports the system hands out to outgoing connections (ephemeral ports), or null when unknown.
+ * Any program's connection can take one of them at any time, so a workspace's ports should lie outside.
+ */
+export function ephemeralRange() {
+  if (cachedRange !== undefined) return cachedRange;
+  cachedRange = null;
+  try {
+    if (process.platform === "win32") {
+      const result = spawn.sync("netsh", ["int", "ipv4", "show", "dynamicport", "tcp"], { encoding: "utf8", windowsHide: true, timeout: 5000 });
+      if (result.status === 0) cachedRange = parseDynamicPorts(result.stdout);
+    } else if (process.platform === "linux") {
+      const [start, end] = readFileSync("/proc/sys/net/ipv4/ip_local_port_range", "utf8").trim().split(/\s+/).map(Number);
+      if (start > 0 && end >= start) cachedRange = { start, end };
+    } else if (process.platform === "darwin") {
+      const result = spawn.sync("sysctl", ["-n", "net.inet.ip.portrange.first", "net.inet.ip.portrange.last"], { encoding: "utf8", timeout: 5000 });
+      const [start, end] = (result.stdout ?? "").trim().split(/\s+/).map(Number);
+      if (result.status === 0 && start > 0 && end >= start) cachedRange = { start, end };
+    }
+  } catch {
+    /* Unknown; nothing is avoided. */
+  }
+  return cachedRange;
+}
+
+/** Whether a workspace's block of ports starting at `start` lies inside the ephemeral range. */
+export function inEphemeral(start, range) {
+  return Boolean(range) && start <= range.end && range.start < start + PORT_BLOCK;
+}
+
+/**
+ * Gives a workspace PORT_BLOCK ports in a row. Skips blocks other workspaces
+ * own, blocks where something is already listening, and blocks the system may
+ * hand to outgoing connections, unless nothing else is left.
+ */
+export async function allocatePort(config, { base = config.port_base ?? DEFAULT_PORT_BASE, isFree = portFree, ephemeral = ephemeralRange() } = {}) {
+  const used = usedPorts(config);
+  for (const avoid of [ephemeral, null]) {
+    for (let start = base; start + PORT_BLOCK - 1 <= MAX_PORT; start += PORT_BLOCK) {
+      if (overlaps(start, used) || inEphemeral(start, avoid)) continue;
+      if (await blockFree(start, isFree)) return start;
+    }
+  }
+  throw new NookError(`No free block of ${PORT_BLOCK} ports from ${base}`);
+}