@futuristic.digital/pick-ports 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,96 @@
-# Temporary Holding Version
+# `@futuristic.digital/pick-ports`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Run a command with available TCP ports assigned to environment variables. Define
+each variable name and preferred default port directly in your npm script. Uses
+Node.js 22 or newer and has no runtime dependencies.
+
+```sh
+npm install --save-dev @futuristic.digital/pick-ports
+```
+
+```json
+{
+  "scripts": {
+    "dev": "pick-ports WEB_PORT=3000 ADMIN_PORT=3001 API_PORT=3100 -- turbo run dev"
+  }
+}
+```
+
+`npm run dev` checks all preferred defaults first. An available default is used;
+otherwise the OS chooses an available port. Defaults that cannot be bound because
+of permissions also fall back to an OS-assigned port. Each variable gets a distinct port,
+even when defaults repeat. Assignments override existing values in the child
+environment. Other environment variables, command arguments, terminal input and
+output, and the command's exit status are preserved. The selected mapping is
+printed to stderr before the command starts.
+
+You can also invoke it without installing it locally:
+
+```sh
+npm exec --package=@futuristic.digital/pick-ports -- pick-ports WEB_PORT=3000 API_PORT=3100 -- turbo run dev
+```
+
+## Use the variables in applications
+
+The command after `--` and its descendants inherit the variables. For Turbo's
+strict environment mode, allow them through in the consuming project's
+`turbo.json`:
+
+```json
+{
+  "tasks": {
+    "dev": {
+      "cache": false,
+      "persistent": true,
+      "passThroughEnv": ["WEB_PORT", "ADMIN_PORT", "API_PORT"]
+    }
+  }
+}
+```
+
+An application's npm script can then read its assigned variable:
+
+```json
+{
+  "scripts": {
+    "dev": "next dev --port $WEB_PORT"
+  }
+}
+```
+
+This variable expansion example uses a POSIX shell. The launcher passes arguments
+directly to the child; it does not interpret shell expressions. Use a child npm
+script or an explicit shell if expansion is needed. For example,
+`pick-ports WEB_PORT=3000 -- npm run dev:app` lets `dev:app` expand `$WEB_PORT`
+after allocation. Putting `$WEB_PORT` directly after `--` in the outer script
+would expand it too early. On Windows, use a Node launcher to read `process.env`
+and spawn the application, or invoke shell commands through `cmd.exe /c`.
+
+## Scope and availability
+
+- Pass at least one `NAME=PORT` assignment and a command after `--`. Names use
+  letters, digits, and underscores, starting with a letter or underscore. Names
+  must be unique (case-insensitively); default ports must be integers from 1 to 65535. A repeated default goes to the first variable that requests it.
+- Ports are checked with wildcard TCP listeners using Node's default network
+  binding. UDP availability is not checked.
+- Reservations stay open while allocating the full mapping, then close before
+  starting the child. Another process can claim a port between allocation and
+  application startup; this tool cannot guarantee a later bind will succeed.
+- Values exist in the child environment only. A process cannot change the parent
+  shell's environment. No env files or saved port registry are written.
+- URLs are not derived automatically. Build local URLs from the assigned port
+  variables in your application's configuration or a child launcher. Remove stale
+  hardcoded URLs and ports from local env files as needed.
+
+Run `pick-ports --help` for the argument syntax.
+
+## Development
+
+From the repository root, run the pure argument-parser tests with:
+
+```sh
+npm run test --workspace @futuristic.digital/pick-ports
+```
+
+These tests cover input validation and argument preservation; they do not exercise
+TCP allocation or child-process lifecycle behavior.

package/package.json

@@ -1,6 +1,23 @@
 {
   "name": "@futuristic.digital/pick-ports",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Run a command with available TCP ports assigned to environment variables.",
+  "type": "module",
+  "scripts": {
+    "test": "vitest run"
+  },
+  "bin": {
+    "pick-ports": "pick-ports.mjs"
+  },
+  "files": [
+    "pick-ports.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/pick-ports.mjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+
+/** Allocate ports together before starting a command with their environment. */
+import { spawn } from "node:child_process";
+import console from "node:console";
+import { realpathSync } from "node:fs";
+import { createServer } from "node:net";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+const usage = `Usage: pick-ports NAME=DEFAULT_PORT [NAME=DEFAULT_PORT ...] -- command [args...]
+
+Example: pick-ports WEB_PORT=3000 API_PORT=3100 -- turbo run dev
+
+Each default must be an integer from 1 to 65535. Occupied defaults fall back
+to distinct OS-assigned TCP ports. Values override the child's environment.`;
+
+// Argument parsing
+
+/**
+ * Validate user input before opening sockets or starting a child process.
+ * @param {string[]} args CLI arguments without the Node and script paths.
+ */
+export function parseArguments(args) {
+  const separator = args.indexOf("--");
+  const command = args[separator + 1];
+  if (separator < 1 || !command) {
+    throw new Error(usage);
+  }
+
+  const defaults = new Map();
+  for (const assignment of args.slice(0, separator)) {
+    const match = /^([A-Za-z_][A-Za-z0-9_]*)=([0-9]+)$/.exec(assignment);
+    if (!match) {
+      throw new Error(`Invalid assignment: ${assignment}. Expected NAME=PORT.`);
+    }
+    const [, name, portText] = match;
+    const port = Number(portText);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+      throw new Error(`Invalid port for ${name}: ${portText}. Use 1–65535.`);
+    }
+    // Environment names are case-insensitive on Windows.
+    if (
+      [...defaults.keys()].some(
+        (key) => key.toUpperCase() === name.toUpperCase()
+      )
+    ) {
+      throw new Error(`Duplicate environment variable: ${name}.`);
+    }
+    defaults.set(name, port);
+  }
+
+  return { defaults, command, commandArgs: args.slice(separator + 2) };
+}
+
+// Port allocation
+
+/** Keep a TCP port reserved until all variables have distinct assignments. */
+async function reservePort(port) {
+  const server = createServer();
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen({ port, exclusive: true }, resolve);
+  });
+  return server;
+}
+
+/** Prefer every requested default before asking the OS for fallback ports. */
+async function allocatePorts(defaults) {
+  const reservations = new Map();
+  try {
+    // Claim defaults first so a fallback cannot take another variable's default.
+    for (const [name, port] of defaults) {
+      try {
+        reservations.set(name, await reservePort(port));
+      } catch (error) {
+        if (
+          !(error instanceof Error) ||
+          !("code" in error) ||
+          !["EADDRINUSE", "EACCES"].includes(error.code)
+        ) {
+          throw error;
+        }
+      }
+    }
+
+    for (const name of defaults.keys()) {
+      if (!reservations.has(name)) {
+        reservations.set(name, await reservePort(0));
+      }
+    }
+
+    return Object.fromEntries(
+      [...reservations].map(([name, server]) => [
+        name,
+        String(server.address().port)
+      ])
+    );
+  } finally {
+    // Applications need to bind the ports themselves, so release before spawn.
+    await Promise.all(
+      [...reservations.values()].map(
+        (server) => new Promise((resolve) => server.close(resolve))
+      )
+    );
+  }
+}
+
+// Command lifecycle
+
+/** Preserve arguments, terminal IO, exit codes, and termination signals. */
+async function runCommand(command, args, ports) {
+  const child = spawn(command, args, {
+    env: { ...process.env, ...ports },
+    stdio: "inherit"
+  });
+  const signalHandlers = new Map(
+    ["SIGINT", "SIGTERM", "SIGHUP"].map((signal) => [
+      signal,
+      () => child.kill(signal)
+    ])
+  );
+  for (const [signal, handler] of signalHandlers) process.on(signal, handler);
+
+  let result;
+  try {
+    result = await new Promise((resolve, reject) => {
+      child.once("error", reject);
+      child.once("exit", (code, signal) => resolve({ code, signal }));
+    });
+  } finally {
+    for (const [signal, handler] of signalHandlers)
+      process.off(signal, handler);
+  }
+
+  if (result.signal) {
+    process.kill(process.pid, result.signal);
+  } else {
+    process.exitCode = result.code;
+  }
+}
+
+/** Resolve the complete mapping once so every child receives the same values. */
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 1 && ["--help", "-h"].includes(args[0])) {
+    console.log(usage);
+    return;
+  }
+
+  const { defaults, command, commandArgs } = parseArguments(args);
+  const ports = await allocatePorts(defaults);
+  console.error(
+    `[pick-ports] ${Object.entries(ports)
+      .map(([name, port]) => `${name}=${port}`)
+      .join(" ")}`
+  );
+  await runCommand(command, commandArgs, ports);
+}
+
+// Imports expose the pure parser without launching a command. Resolve npm's bin symlink.
+if (
+  process.argv[1] &&
+  realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+  try {
+    await main();
+  } catch (error) {
+    console.error(
+      `[pick-ports] ${error instanceof Error ? error.message : String(error)}`
+    );
+    process.exitCode = 1;
+  }
+}