@codeyam-editor/codeyam-editor 0.1.4 → 0.1.6

package/npm/utils.js

@@ -2,6 +2,7 @@ const { execSync, spawn, spawnSync } = require("child_process");
 const net = require("net");
 const path = require("path");
 const fs = require("fs");
+const readline = require("readline");
 
 const rootDir = path.resolve(__dirname, "..");
 const serverStatePath = path.join(rootDir, ".codeyam", "server-state.json");
@@ -102,6 +103,34 @@ function findBinary() {
   return null;
 }
 
+/**
+ * Whether this install is a dev checkout (the source tree) rather than an
+ * npm-installed package. Signalled by a `Cargo.toml` at `rootDir` — present in
+ * the git checkout, absent in the npm install dir. The single source of truth
+ * for the checkout-vs-installed distinction; both `ensureBinary` (build-from-
+ * source vs error) and `serverSpawnEnv` (distribution-channel gating) read it.
+ * Accepts an explicit dir so it is unit-testable against a temp tree.
+ */
+function isDevCheckout(dir = rootDir) {
+  return fs.existsSync(path.join(dir, "Cargo.toml"));
+}
+
+/**
+ * Env for a launched editor-server, tagging the distribution channel so the
+ * server's update-availability check knows an npm install can be upgraded via
+ * `npm install -g …@latest`. Pure: returns a NEW object, never mutates the
+ * input.
+ *
+ * Installed (non-dev-checkout) → set `CODEYAM_DISTRIBUTION=npm`, so the server
+ * polls the npm registry and surfaces the upgrade banner. Dev checkout → leave
+ * the env untouched (any pre-existing value from the parent env is preserved),
+ * so a `codeyam-editor` run from source is never nagged to "upgrade".
+ */
+function serverSpawnEnv(baseEnv, { devCheckout } = {}) {
+  if (devCheckout) return { ...baseEnv };
+  return { ...baseEnv, CODEYAM_DISTRIBUTION: "npm" };
+}
+
 /**
  * Return the binary path, building from source if we're in a dev checkout.
  *
@@ -119,9 +148,9 @@ function ensureBinary() {
   const existing = findBinary();
   if (existing) return existing;
 
-  const isDevCheckout = fs.existsSync(path.join(rootDir, "Cargo.toml"));
+  const devCheckout = isDevCheckout();
 
-  if (!isDevCheckout) {
+  if (!devCheckout) {
     const info = platformPackageInfo();
     if (!info) {
       console.error(
@@ -276,6 +305,25 @@ function enforceFreshBinary(buildOk, { action, continueVerb = "continuing with"
   );
 }
 
+// Default boot budget for the editor server. A real cold boot legitimately
+// spends ~7–10s on plan-claims git migration + reap, a PTY-broker probe/respawn
+// (worse when a stale orphan broker's socket is dead), and a branch-tip fetch.
+// 30s is ~3× that — comfortable headroom without letting a genuinely hung
+// server hang indefinitely.
+const DEFAULT_START_TIMEOUT_MS = 30000;
+
+/**
+ * Resolve the boot budget (ms) for `ensureServer`, honoring the
+ * `CODEYAM_EDITOR_START_TIMEOUT_MS` override. Mirrors the existing env-read
+ * style (`CODEYAM_ALLOW_STALE`): parse the raw value, accept only a positive
+ * integer, and fall back to the 30s default on missing/non-numeric/≤0 input.
+ * Exported so it's unit-testable without spawning the real binary.
+ */
+function resolveStartTimeoutMs(env = process.env) {
+  const parsed = Number.parseInt(env.CODEYAM_EDITOR_START_TIMEOUT_MS, 10);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : DEFAULT_START_TIMEOUT_MS;
+}
+
 function isPlainJsonObject(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -491,9 +539,14 @@ async function requestServerShutdown(port = 14199, timeoutMs = 1500) {
 
 /**
  * GET /api/codeyam-server-identity from the listener on `port` with a
- * sub-second timeout. Returns the parsed `{projectDir, pid, version,
- * startedAt}` body on a 2xx response, or `null` on any failure
- * (timeout, non-200, parse failure, connection refused).
+ * sub-second timeout. Returns the parsed identity body on a 2xx response,
+ * or `null` on any failure (timeout, non-200, parse failure, connection
+ * refused). Two identity shapes are recognized:
+ *   - a per-project editor: `{projectDir, pid, version, startedAt}`
+ *   - the Project Launcher (selector): `{role: "launcher", pid, version}`
+ *     — deliberately NO `projectDir`, since the selector isn't bound to one
+ *     project. We must NOT reject it for the missing `projectDir`, or the
+ *     wrapper would misclassify the live selector as a foreign squatter.
  *
  * `null` carries two distinct meanings that the caller must
  * disambiguate by also checking `isPortInUse`:
@@ -513,9 +566,10 @@ async function fetchServerIdentity(port, timeoutMs = 500) {
     });
     if (!resp.ok) return null;
     const body = await resp.json();
-    if (!body || typeof body !== "object" || typeof body.projectDir !== "string") {
-      return null;
-    }
+    if (!body || typeof body !== "object") return null;
+    // The Project Launcher advertises a `launcher` role and no projectDir.
+    if (body.role === "launcher") return body;
+    if (typeof body.projectDir !== "string") return null;
     return body;
   } catch {
     return null;
@@ -572,11 +626,47 @@ function formatCrossProjectError(port, holder, verb) {
   );
 }
 
+/**
+ * Build the "server never bound the port" failure message, shown only after
+ * the boot budget AND one automatic retry have both been exhausted. Pure
+ * string builder (same shape as `formatForeignListenerError` /
+ * `formatCrossProjectError`): names what happened, the likely cause, where to
+ * look, and concrete next steps. Stack-agnostic — no app-type/framework
+ * assumptions.
+ */
+function formatServerStartTimeoutError(port, timeoutMs) {
+  const seconds = Math.round(timeoutMs / 1000);
+  return [
+    `codeyam-editor server did not bind port ${port} within ${seconds}s, ` +
+      `even after one automatic retry.`,
+    "",
+    "Likely cause: a slow cold boot (plan-claims git migration, PTY-broker " +
+      "respawn) — often a stale codeyam-editor-pty-broker whose socket is gone.",
+    "",
+    "Or: with 2+ projects registered this launch diverts to the Project " +
+      "Launcher (selector). An old binary that still discards --port binds the " +
+      "selector on a DIFFERENT ephemeral port, so the wait for this one times " +
+      "out — check .codeyam/logs/editor-server.out.log for a `Project Launcher " +
+      "running at` line and rebuild the editor.",
+    "",
+    "Where to look:",
+    "  .codeyam/logs/editor-server.log",
+    "  .codeyam/logs/editor-server.out.log",
+    "",
+    "What to try:",
+    "  - Re-run the launcher.",
+    "  - If a stale codeyam-editor-pty-broker is lingering, kill it, then re-run.",
+    "  - If boots are consistently slow, raise the budget, e.g. " +
+      "CODEYAM_EDITOR_START_TIMEOUT_MS=60000.",
+  ].join("\n");
+}
+
 /**
  * Classify whatever is listening on `port` relative to `projectDir`.
  * Returns one of:
  *   - `{ kind: "free" }`                    — nothing on the port
  *   - `{ kind: "foreign" }`                 — port held by a non-editor process
+ *   - `{ kind: "launcher", identity }`      — held by the Project Launcher (selector)
  *   - `{ kind: "cross-project", wantDir, haveDir, identity }`
  *                                           — held by another project's editor
  *   - `{ kind: "same-project", identity }`  — held by THIS project's editor
@@ -596,6 +686,12 @@ async function classifyPortHolder(port, projectDir = process.cwd()) {
   if (identity === null) {
     return { kind: "foreign" };
   }
+  // The Project Launcher (selector) holds the port in multi-project mode. It is
+  // codeyam-editor, not a foreign process and not a per-project editor, so it
+  // gets its own kind — the caller just re-opens it rather than refusing.
+  if (identity.role === "launcher") {
+    return { kind: "launcher", identity };
+  }
   const wantDir = await canonicalisePath(projectDir);
   const haveDir = await canonicalisePath(identity.projectDir);
   if (wantDir !== haveDir) {
@@ -631,6 +727,76 @@ function isInteractiveLauncher(stream = process.stdout) {
   return Boolean(stream && stream.isTTY);
 }
 
+/**
+ * Ask a yes/no question at the terminal and resolve `true` only on an
+ * affirmative `y`/`yes` (case-insensitive). A bare Enter, EOF, `n`, or any
+ * other text resolves `false` — the safe default for a destructive prompt.
+ *
+ * Mirrors `promptForInstanceName` in `npm/cloud.js`: readline reads from stdin
+ * and writes its prompt to stderr by default, so the question never pollutes a
+ * piped stdout. `input`/`output` are injectable so the helper is unit-testable
+ * by feeding a fake stream without a real TTY.
+ */
+function promptYesNo(question, { input = process.stdin, output = process.stderr } = {}) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input, output });
+    rl.question(question, (ans) => {
+      rl.close();
+      const normalized = String(ans).trim().toLowerCase();
+      resolve(normalized === "y" || normalized === "yes");
+    });
+  });
+}
+
+/**
+ * Decide what to do when `port` is held by a DIFFERENT project's editor server.
+ *
+ * Policy (shared by both launcher entry points so the wording and gating stay
+ * identical):
+ *   - Non-interactive launcher (cloud container, agent-driven, piped/CI): print
+ *     `formatCrossProjectError` and return `{ action: "abort" }` — never kill
+ *     another project's server without a human at the keyboard, since the kill
+ *     also tears down any Claude agent attached via the PTY broker.
+ *   - Interactive launcher: print the full who/what/where, then ask whether to
+ *     stop the other server and take over. On `y` → `stopServer(port)` and
+ *     return `{ action: "took-over" }`. On anything else → `{ action: "declined" }`.
+ *
+ * Gates on `process.stdin.isTTY` (the INPUT stream — a human can only answer a
+ * prompt when stdin is a terminal), not stdout. The resolver prints the full
+ * `formatCrossProjectError` message in BOTH the abort and the interactive paths,
+ * so the caller only decides exit-vs-continue.
+ *
+ * Dependencies are injected (defaulting to the real implementations) so the
+ * resolver is unit-testable without a TTY or a live server — same style as
+ * `classifyPortHolder` / `resolveBootedServer`.
+ */
+async function resolveCrossProjectCollision(
+  port,
+  holder,
+  verb,
+  {
+    isInteractive = isInteractiveLauncher,
+    prompt = promptYesNo,
+    stop = stopServer,
+  } = {},
+) {
+  console.error(formatCrossProjectError(port, holder, verb));
+  if (!isInteractive(process.stdin)) {
+    return { action: "abort" };
+  }
+  const pidNote = Number.isInteger(holder.identity && holder.identity.pid)
+    ? ` (pid ${holder.identity.pid})`
+    : "";
+  const accepted = await prompt(
+    `\nKill that server${pidNote} and start this project's editor instead? [y/N] `,
+  );
+  if (!accepted) {
+    return { action: "declined" };
+  }
+  await stop(port);
+  return { action: "took-over" };
+}
+
 /**
  * Spawn options for the editor server child. The server is spawned `detached:
  * true` so it leads its OWN session + process group (setsid), decoupling its
@@ -742,22 +908,60 @@ function killChildProcess(child) {
   }
 }
 
-function findListeningPids(port) {
-  // Process discovery on Windows is best-effort — `lsof` is not installed and
-  // a `netstat -ano` parser is a follow-up. The API-shutdown path and the
-  // PID-file path together stop the server cleanly in normal operation.
-  if (process.platform === "win32") return [];
+/** Parse `lsof -t` stdout (one pid per line) into an array of integer pids. */
+function parseLsofPids(stdout) {
+  return (stdout || "")
+    .split(/\s+/)
+    .map((line) => parseInt(line, 10))
+    .filter((pid) => Number.isInteger(pid));
+}
 
-  const result = spawnSync("lsof", [`-tiTCP:${port}`, "-sTCP:LISTEN"], {
+/** Run `lsof` for the listeners on a TCP port. Returns the raw spawnSync
+ * result (`{ error?, stdout }`) so callers can distinguish a spawn failure
+ * from a genuinely empty result. */
+function defaultRunLsof(port) {
+  return spawnSync("lsof", [`-tiTCP:${port}`, "-sTCP:LISTEN"], {
     encoding: "utf8",
   });
+}
 
-  if (result.error) return [];
+/** Synchronous millisecond sleep — used to back off between lsof retries. */
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
 
-  return result.stdout
-    .split(/\s+/)
-    .map((line) => parseInt(line, 10))
-    .filter((pid) => Number.isInteger(pid));
+/**
+ * Find the pids listening on a TCP port via `lsof`. Returns [] on Windows
+ * (lsof absent) or when no process is listening.
+ *
+ * A transient *spawn* failure (e.g. fork `EAGAIN` under heavy concurrent load —
+ * the cause of the flaky multi-runner test failure) is RETRIED with a short
+ * backoff rather than swallowed into "no listeners found". This matters because
+ * `findListeningPids` feeds `stopServer`: a one-off lsof spawn error must not be
+ * mistaken for "the server isn't running" and leave it alive. A clean run that
+ * legitimately reports no listeners returns [] on the first attempt (no error,
+ * so no retry) — free-port behavior and latency are unchanged.
+ *
+ * `runLsof` and `sleep` are injectable so the retry path is unit-testable
+ * without depending on real system load.
+ */
+function findListeningPids(port, runLsof = defaultRunLsof, sleep = sleepSync) {
+  // Process discovery on Windows is best-effort — `lsof` is not installed and
+  // a `netstat -ano` parser is a follow-up. The API-shutdown path and the
+  // PID-file path together stop the server cleanly in normal operation.
+  if (process.platform === "win32") return [];
+
+  const MAX_ATTEMPTS = 5;
+  const BACKOFF_MS = 50;
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+    const result = runLsof(port);
+    // No spawn error → trust the result (empty stdout legitimately means "no
+    // listeners"; a non-empty stdout yields the pids).
+    if (!result.error) return parseLsofPids(result.stdout);
+    // Transient spawn failure — back off and retry, unless we're out of tries.
+    if (attempt < MAX_ATTEMPTS) sleep(BACKOFF_MS);
+  }
+  return [];
 }
 
 /** Stop the Rust backend server if it is running. */
@@ -819,10 +1023,31 @@ async function ensureServer(port = 14199) {
       console.error(formatForeignListenerError(port));
       process.exit(1);
       break;
-    case "cross-project":
-      console.error(formatCrossProjectError(port, holder, "attach"));
+    case "cross-project": {
+      const outcome = await resolveCrossProjectCollision(port, holder, "attach");
+      if (outcome.action === "took-over") {
+        // `stopServer` already waited for the port to close, so fall through to
+        // the fresh-boot path below — `spawnAndAwait` binds the now-free port.
+        break;
+      }
+      // "abort" (non-TTY) or "declined" (user said no): the resolver already
+      // printed the cross-project message. On decline, remind how to keep both.
+      if (outcome.action === "declined") {
+        console.error(
+          "Leaving the existing server running. Change controlPort in " +
+            ".codeyam/editor.local.json to run both, e.g.:\n" +
+            "  codeyam-editor editor config-override proxy.controlPort 14399",
+        );
+      }
       process.exit(1);
       break;
+    }
+    case "launcher":
+      // The selector is already up on this port (multi-project mode). Treat it
+      // like an already-running same-project server: don't refuse, don't
+      // double-spawn — just let the caller re-open the port.
+      console.error(`Project selector already running on port ${port}`);
+      return null;
     case "same-project":
       console.error(`Server already running on port ${port}`);
       return null;
@@ -832,6 +1057,12 @@ async function ensureServer(port = 14199) {
   }
 
   const binary = ensureBinary();
+  const startTimeoutMs = resolveStartTimeoutMs();
+
+  // Spawn a fresh server child and race its boot against `timeoutMs`. Factored
+  // into a closure so the auto-retry path re-runs an identical spawn with a
+  // longer budget without duplicating the spawn options.
+  //
   // UI bundle is embedded in the Rust binary; CODEYAM_EDITOR_UI_DIR is
   // now an explicit dev-override only.
   //
@@ -843,43 +1074,117 @@ async function ensureServer(port = 14199) {
   // `.codeyam/logs/editor-server.out.log` (the Rust server also writes its own
   // editor-server.log). `unref()` keeps the detached child from pinning the
   // launcher's event loop alive on its own.
-  const logFd = openServerOutputLog(process.cwd());
-  const child = spawn(
-    binary,
-    ["start", "--no-open", "--port", String(port)],
-    buildServerSpawnOptions({ cwd: process.cwd(), env: process.env, logFd }),
-  );
-  if (logFd !== null) {
-    try {
-      fs.closeSync(logFd);
-    } catch {
-      /* child holds its own dup of the fd; the launcher's copy is no longer needed */
+  const spawnAndAwait = async (timeoutMs) => {
+    const logFd = openServerOutputLog(process.cwd());
+    const child = spawn(
+      binary,
+      ["start", "--no-open", "--port", String(port)],
+      buildServerSpawnOptions({
+        cwd: process.cwd(),
+        env: serverSpawnEnv(process.env, { devCheckout: isDevCheckout() }),
+        logFd,
+      }),
+    );
+    if (logFd !== null) {
+      try {
+        fs.closeSync(logFd);
+      } catch {
+        /* child holds its own dup of the fd; the launcher's copy is no longer needed */
+      }
     }
+    child.unref();
+    const race = await awaitServerReadyOrChildExit(child, port, (p) =>
+      waitForPort(p, timeoutMs),
+    );
+    return { child, ...race };
+  };
+
+  // Orchestrate the boot (re-check-before-kill + one auto-retry) with the real
+  // effects injected, then map the discriminated result onto the process-exit
+  // policy. Keeping the orchestration in `resolveBootedServer` (pure control
+  // flow over injected effects) is what makes the re-check guard and the retry
+  // unit-testable without spawning the real binary or stubbing process.exit.
+  const result = await resolveBootedServer({
+    port,
+    startTimeoutMs,
+    spawnAndAwait,
+    isPortInUseFn: isPortInUse,
+  });
+  switch (result.kind) {
+    case "ready":
+      return result.child;
+    case "early-exit": {
+      // A genuine early exit (preflight bail) is always a hard fail — even on
+      // code 0: the caller needs to know the server isn't running.
+      const { code, signal } = result.exitedBeforeBind ?? { code: null, signal: null };
+      const detail = signal != null ? `signal ${signal}` : `code ${code}`;
+      console.error(
+        `codeyam-editor server exited (${detail}) before binding port ${port}. ` +
+          "Likely a preflight bail; see .codeyam/logs/editor-server.out.log " +
+          "and .codeyam/logs/editor-server.log.",
+      );
+      process.exit(code != null && code !== 0 ? code : 1);
+      break;
+    }
+    case "timeout-exhausted":
+    default:
+      console.error(formatServerStartTimeoutError(port, result.retryTimeoutMs));
+      process.exit(1);
   }
-  child.unref();
+}
+
+/**
+ * Boot orchestration for `ensureServer`, isolated from the process-exit policy
+ * and from the spawn/port effects so the re-check-before-kill guard and the
+ * single auto-retry are unit-testable. Pure control flow over two injected
+ * effects:
+ *   - `spawnAndAwait(timeoutMs)` → `{ child, outcome, exitedBeforeBind }` —
+ *     one boot attempt racing the port against the child exit.
+ *   - `isPortInUseFn(port)` → bool — the final re-check probe.
+ *
+ * Returns a discriminated result the caller maps to an action:
+ *   - `{ kind: "ready", child }`                  — server bound; keep this child.
+ *   - `{ kind: "early-exit", exitedBeforeBind }`  — child exited before bind
+ *     (preflight bail); a hard fail, never retried.
+ *   - `{ kind: "timeout-exhausted", retryTimeoutMs }` — both the budget and a
+ *     longer-budget retry missed; give up with actionable guidance.
+ *
+ * The destructive `child.kill()` only fires after a re-check confirms the port
+ * is NOT listening — a server that bound a hair after the deadline is kept, not
+ * torn down (the reported race). The retry runs at most once.
+ */
+async function resolveBootedServer({ port, startTimeoutMs, spawnAndAwait, isPortInUseFn }) {
+  // One boot attempt, with the re-check folded in: a post-deadline bind is
+  // reported as "ready" rather than "timeout" so the caller never kills it.
+  const attempt = async (timeoutMs) => {
+    const { child, outcome, exitedBeforeBind } = await spawnAndAwait(timeoutMs);
+    if (outcome === "ready") return { kind: "ready", child };
+    if (outcome === "exited" || (outcome === "timeout" && exitedBeforeBind !== null)) {
+      return { kind: "early-exit", exitedBeforeBind };
+    }
+    // Genuine timeout — re-check before reporting a miss.
+    if (await isPortInUseFn(port)) return { kind: "ready", child };
+    return { kind: "timeout", child };
+  };
 
-  const { outcome, exitedBeforeBind } = await awaitServerReadyOrChildExit(child, port);
+  const first = await attempt(startTimeoutMs);
+  if (first.kind !== "timeout") return first;
 
-  if (outcome === "exited" || (outcome === "timeout" && exitedBeforeBind !== null)) {
-    const { code, signal } = exitedBeforeBind ?? { code: null, signal: null };
-    const detail = signal != null ? `signal ${signal}` : `code ${code}`;
-    console.error(
-      `codeyam-editor server exited (${detail}) before binding port ${port}. ` +
-        "Likely a preflight bail; see .codeyam/logs/editor-server.out.log " +
-        "and .codeyam/logs/editor-server.log.",
-    );
-    // Always propagate as a real failure — even on code 0 the caller
-    // needs to know the server isn't running.
-    process.exit(code != null && code !== 0 ? code : 1);
-  }
+  // The boot was just slow (cold caches, broker respawn). Kill the stalled
+  // attempt and auto-retry ONCE with a longer budget — a single retry, not a
+  // loop, so a truly broken server isn't masked behind endless retries.
+  const retryTimeoutMs = startTimeoutMs * 2;
+  console.error(
+    `Server did not bind port ${port} within ${Math.round(startTimeoutMs / 1000)}s; ` +
+      `retrying once with a longer budget...`,
+  );
+  first.child.kill();
 
-  if (outcome === "timeout") {
-    console.error("Server failed to start within 10 seconds");
-    child.kill();
-    process.exit(1);
-  }
+  const second = await attempt(retryTimeoutMs);
+  if (second.kind !== "timeout") return second;
 
-  return child;
+  second.child.kill();
+  return { kind: "timeout-exhausted", retryTimeoutMs };
 }
 
 /**
@@ -919,6 +1224,8 @@ module.exports = {
   findBrokerBinary,
   verifyBrokerBinaryPresent,
   ensureBinary,
+  isDevCheckout,
+  serverSpawnEnv,
   staleBinaryBanner,
   enforceFreshBinary,
   uiDistDir,
@@ -934,13 +1241,19 @@ module.exports = {
   classifyPortHolder,
   formatForeignListenerError,
   formatCrossProjectError,
+  formatServerStartTimeoutError,
+  resolveStartTimeoutMs,
   tryKillPid,
   findListeningPids,
+  parseLsofPids,
   stopServer,
   restartServer,
   ensureServer,
+  resolveBootedServer,
   awaitServerReadyOrChildExit,
   isInteractiveLauncher,
+  promptYesNo,
+  resolveCrossProjectCollision,
   buildServerSpawnOptions,
   openServerOutputLog,
   formatLauncherSignalRecord,

package/npm/vm-urls.js

@@ -68,25 +68,82 @@ function normalizeVmNumber(n) {
   return num;
 }
 
+// A single lowercase DNS label: 1–63 chars of letters/digits/hyphen, no leading
+// or trailing hyphen, NO dots. A custom slug becomes the leftmost label of a
+// `<slug>.<surface>.<domain>` host the wildcard cert (`*.editor.<domain>`) and
+// the wildcard `A` records already cover, so it must be exactly one label —
+// `my.slug` would escape the wildcard and resolve nowhere.
+const SLUG_RE = /^(?!-)[a-z0-9-]{1,63}(?<!-)$/;
+
+// Slugs that would collide with a fixed fleet surface. `dashboard.<domain>` is
+// the operator dashboard's own host; `editor` / `preview` are the per-VM surface
+// labels in `<slug>.editor.<domain>` — a slug of `editor` would mint the
+// nonsensical `editor.editor.<domain>` and shadow the surface segment.
+const RESERVED_SLUGS = Object.freeze(['dashboard', 'editor', 'preview']);
+
+/** Validate + normalize a custom VM slug into a single lowercase DNS label.
+ *  A bad slug would bake a dead host into the URL map or shadow another VM's
+ *  routing, so we reject it loudly at the derivation boundary — the same posture
+ *  as `resolveFleetDomain` / `normalizeVmNumber`. Rejects: anything that isn't a
+ *  single label (dots, leading/trailing hyphen, >63 chars, empty); the reserved
+ *  words `dashboard` / `editor` / `preview`; and the `vm-<N>` shape, which would
+ *  collide with the numeric scheme. Returns the trimmed/lowercased slug. */
+function normalizeVmSlug(slug) {
+  if (slug == null) throw new Error('VM slug is required');
+  const s = String(slug).trim().toLowerCase();
+  if (!SLUG_RE.test(s)) {
+    throw new Error(
+      `VM slug "${slug}" is not a valid single DNS label ` +
+        '(lowercase letters, digits, hyphens; no dots; 1–63 chars; ' +
+        'no leading/trailing hyphen)',
+    );
+  }
+  if (RESERVED_SLUGS.includes(s)) {
+    throw new Error(
+      `VM slug "${s}" is reserved (${RESERVED_SLUGS.join(', ')})`,
+    );
+  }
+  if (/^vm-\d+$/.test(s)) {
+    throw new Error(
+      `VM slug "${s}" collides with the numeric vm-<N> scheme — pick a name`,
+    );
+  }
+  return s;
+}
+
+/** The leftmost hostname label for a VM: the validated `slug` when supplied,
+ *  else the numeric `vm-<N>` default. Single-sources the "slug overrides the
+ *  number, otherwise fall back" rule every hostname derivation shares. */
+function vmLabel(n, slug) {
+  if (slug != null && String(slug).trim() !== '') return normalizeVmSlug(slug);
+  return `vm-${normalizeVmNumber(n)}`;
+}
+
 /** The bare per-VM hostnames (no scheme), derived from the VM number + domain.
  *  `editor` fronts the in-VM editor control API; `preview` fronts the VM's dev
  *  server (the Live Preview). These are what the named-tunnel ingress rules and
- *  the DNS CNAME records are keyed on — see named-tunnel-config.sh. */
-function vmHostnames(n, domain) {
-  const num = normalizeVmNumber(n);
+ *  the DNS CNAME records are keyed on — see named-tunnel-config.sh.
+ *
+ *  An optional `slug` overrides the leftmost `vm-<N>` label with a human-readable
+ *  name (`<slug>.editor.<domain>`); with no slug the output is byte-for-byte the
+ *  numeric scheme, so the change is a no-op for every existing caller. */
+function vmHostnames(n, domain, slug) {
+  const label = vmLabel(n, slug); // validates n (and slug, when present)
   if (!domain) throw new Error('vmHostnames requires a fleet domain');
   return {
-    editor: `vm-${num}.editor.${domain}`,
-    preview: `vm-${num}.preview.${domain}`,
+    editor: `${label}.editor.${domain}`,
+    preview: `${label}.preview.${domain}`,
   };
 }
 
 /** The per-VM public HTTPS URLs, derived from the VM number + domain. The
  *  deterministic replacement for `cloudflared-urls.json[n]` /
  *  `cloudflared-urls.json[n-preview]` — same shape the dashboard surfaced from
- *  the monitor's recordings, now with no recording, probing, or rotation. */
-function vmUrls(n, domain) {
-  const host = vmHostnames(n, domain);
+ *  the monitor's recordings, now with no recording, probing, or rotation. An
+ *  optional `slug` rides through to `vmHostnames` so the URLs carry the custom
+ *  hostname; absent, they are unchanged. */
+function vmUrls(n, domain, slug) {
+  const host = vmHostnames(n, domain, slug);
   return {
     editor: `https://${host.editor}`,
     preview: `https://${host.preview}`,
@@ -108,8 +165,12 @@ function dashboardUrl(domain) {
 
 module.exports = {
   FLEET_DOMAIN_ENV,
+  SLUG_RE,
+  RESERVED_SLUGS,
   resolveFleetDomain,
   normalizeVmNumber,
+  normalizeVmSlug,
+  vmLabel,
   vmHostnames,
   vmUrls,
   dashboardHostname,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codeyam-editor/codeyam-editor",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Language-agnostic managed execution sandbox for scenario-driven development",
   "bin": {
     "codeyam-editor": "./npm/cli.js"
@@ -9,10 +9,10 @@
     "playwright": "^1.58.2"
   },
   "optionalDependencies": {
-    "@codeyam-editor/codeyam-editor-darwin-arm64": "0.1.4",
-    "@codeyam-editor/codeyam-editor-darwin-x64": "0.1.4",
-    "@codeyam-editor/codeyam-editor-linux-x64": "0.1.4",
-    "@codeyam-editor/codeyam-editor-win32-x64": "0.1.4"
+    "@codeyam-editor/codeyam-editor-darwin-arm64": "0.1.6",
+    "@codeyam-editor/codeyam-editor-darwin-x64": "0.1.6",
+    "@codeyam-editor/codeyam-editor-linux-x64": "0.1.6",
+    "@codeyam-editor/codeyam-editor-win32-x64": "0.1.6"
   },
   "keywords": [
     "codeyam",