@codeyam-editor/codeyam-editor 0.1.8 → 0.1.9

package/npm/scenario-issues.js

@@ -7,6 +7,19 @@ function createIssue(kind, message, extra = {}) {
   };
   if (extra.matchedPattern != null) issue.matchedPattern = extra.matchedPattern;
   if (extra.contextSnippet != null) issue.contextSnippet = extra.contextSnippet;
+  // The hydration gate's cross-origin ATTRIBUTION, carried as data rather than
+  // only as prose. A consumer that must act on the verdict — escalating the
+  // preview off the subpath when the counterpart origin hydrates — would
+  // otherwise have to regex the English message, which breaks the moment the
+  // wording is improved. Same conditional shape as the two fields above so an
+  // issue that carries no attribution serializes exactly as it did before.
+  if (extra.crossOrigin != null) issue.crossOrigin = extra.crossOrigin;
+  if (extra.counterpartUrl != null) issue.counterpartUrl = extra.counterpartUrl;
+  // The dev-server-down verdict, carried as data for the same reason as the
+  // attribution fields above: a consumer that must distinguish "the app served
+  // an error" from "the app was not serving at all" should branch on a field,
+  // not on the prose of the message.
+  if (extra.devServerDown != null) issue.devServerDown = extra.devServerDown;
   return issue;
 }
 
@@ -17,6 +30,42 @@ function pushIssue(issues, issue) {
   }
 }
 
+// Derive which origin a capture actually loaded from, and whether that differs
+// from the origin the VIEWER's browser is served.
+//
+// The two can legitimately differ: the capture browser runs where the app is,
+// the viewer may not, and aiming them independently is what makes a capture
+// work on a cloud VM at all. A capture that renders perfectly from the app's
+// own origin while the user's pane sits on `/__codeyam_preview` is a USEFUL
+// result — but only if the difference travels with it instead of having to be
+// inferred from a URL the reader must parse themselves.
+//
+// Both unknowns resolve toward "no split", never toward a guess. A caller that
+// supplies no `viewerOrigin` (every pre-existing call site) and a `url` with no
+// parseable origin both yield `false`, so no existing consumer sees a changed
+// verdict and an unclassifiable capture is never reported as diverging.
+//
+// Deliberately not reusing `isCrossOriginRequest` from scenario-check.js: that
+// module imports THIS one, so depending on it would invert the dependency, and
+// its fail-safe answers a different question (never strip markers) than this
+// one does (never claim a split).
+function deriveOriginSplit(url, viewerOrigin) {
+  let captureOrigin = null;
+  try {
+    captureOrigin = new URL(url).origin;
+  } catch (_) {
+    /* a malformed or relative capture URL has no origin to report */
+  }
+  return {
+    captureOrigin,
+    viewerOrigin: viewerOrigin ?? null,
+    captureOriginDiffersFromViewer:
+      captureOrigin != null &&
+      viewerOrigin != null &&
+      captureOrigin !== viewerOrigin,
+  };
+}
+
 function buildResult({
   loaded,
   hasContent,
@@ -26,7 +75,13 @@ function buildResult({
   unmockedRoutes = [],
   mockUsage = { used: [], unused: [] },
   externalRequests = [],
+  viewerOrigin = null,
 }) {
+  const { captureOrigin, captureOriginDiffersFromViewer } = deriveOriginSplit(
+    url,
+    viewerOrigin,
+  );
+
   return {
     ok: loaded && hasContent && issues.length === 0,
     loaded,
@@ -48,6 +103,11 @@ function buildResult({
     // Requests grouped by origin, split mocked/unmocked and same/cross-origin.
     // The line that ends a "why is this page blank" misdiagnosis.
     externalRequests,
+    // The two hops, named. See `deriveOriginSplit` for why they can differ and
+    // why reporting the difference is not optional.
+    captureOrigin,
+    viewerOrigin,
+    captureOriginDiffersFromViewer,
   };
 }
 
@@ -55,4 +115,5 @@ module.exports = {
   createIssue,
   pushIssue,
   buildResult,
+  deriveOriginSplit,
 };

package/npm/scenario-playwright.js

@@ -928,6 +928,59 @@ async function collectInteractiveLabels(frame) {
   }, INTERACTIVE_SELECTOR);
 }
 
+// How many candidate labels an error message may echo. Deliberately tighter
+// than `collectInteractiveLabels`' own 20-label read cap: the labels are the
+// USER'S page content, so every one printed is a line of their app leaked into
+// the terminal. Enough to answer "did you mean one of these?", not enough to
+// transcribe the page.
+const CANDIDATE_LABEL_CAP = 8;
+
+// Render the candidate labels for an error message, capped and counted. Shared
+// by the no-match and action-failed paths so the echo policy lives in one place.
+async function candidateLabelSummary(frame) {
+  const candidates = await collectInteractiveLabels(frame);
+  if (candidates.length === 0) return "(none found on page)";
+  const shown = candidates.slice(0, CANDIDATE_LABEL_CAP);
+  const rest = candidates.length - shown.length;
+  return rest > 0 ? `${shown.join(", ")} (+${rest} more)` : shown.join(", ");
+}
+
+// Compose the "no element matched" error, branched on the form the caller
+// ACTUALLY passed. Pure and string-returning so both branches are asserted
+// without a browser.
+//
+// The substring advice ("prefer an exact CSS selector") only applies to a text
+// label. Printing it at a caller who already passed `#id` contradicts its own
+// input and reads as misdirection — the failure mode that sent two sessions
+// hunting a selector bug when the page had simply not hydrated. The candidate
+// labels ride with the text branch for the same reason: they answer "did you
+// mean one of these?", a question only a text match can have asked, and every
+// label printed is a line of the user's own page echoed into the terminal.
+function noMatchGuidance({ targetDesc, matchedByText, candidateLabels }) {
+  const queryParamHint =
+    `Many filter/status/sort states are also reachable directly via a ` +
+    `URL query param (e.g. add "?status=active" to the path) with no ` +
+    `interaction at all.`;
+  if (matchedByText) {
+    return (
+      `preview-interact: no element matched ${targetDesc}. ` +
+      `Text is matched as a case-insensitive SUBSTRING, so a misspelled or ` +
+      `over-specific label matches nothing — prefer an exact/role/testid CSS ` +
+      `selector (e.g. {"selector":"[data-testid=\\"save\\"]"}) for a precise ` +
+      `target. ${queryParamHint} ` +
+      `Candidate interactive labels: ${candidateLabels}`
+    );
+  }
+  return (
+    `preview-interact: no element matched ${targetDesc}. ` +
+    `That is already an exact CSS selector, so nothing on the page matches ` +
+    `it as written — confirm the element is present in THIS state (it may be ` +
+    `behind a tab, dialog, or conditional render), that the id/attribute is ` +
+    `spelled as the markup emits it, and that the page rendered and hydrated ` +
+    `at all. ${queryParamHint}`
+  );
+}
+
 // Describe the elements a substring text match resolved, so an ambiguity
 // warning can name the competing controls (e.g. the preset button "Bet" vs the
 // disclosure button "…or bet on"). Reads each matched element's inner text via
@@ -1075,17 +1128,17 @@ async function performInteraction(
   }
 
   if (matchCount === 0) {
-    const candidates = await collectInteractiveLabels(frame);
-    const candidateList =
-      candidates.length > 0 ? candidates.join(", ") : "(none found on page)";
+    // Candidate labels are collected ONLY for the text branch — see
+    // `noMatchGuidance` for why a CSS-selector miss neither needs them nor
+    // should echo the user's page content back at them.
     throw new Error(
-      `preview-interact: no element matched ${targetDesc}. ` +
-        `Text is matched as a case-insensitive SUBSTRING, so a misspelled or ` +
-        `over-specific label matches nothing — prefer an exact/role/testid CSS ` +
-        `selector (e.g. {"selector":"[data-testid=\\"save\\"]"}) for a precise ` +
-        `target. Many filter/status/sort states are also reachable directly via a ` +
-        `URL query param (e.g. add "?status=active" to the path) with no ` +
-        `interaction at all. Candidate interactive labels: ${candidateList}`,
+      noMatchGuidance({
+        targetDesc,
+        matchedByText,
+        candidateLabels: matchedByText
+          ? await candidateLabelSummary(frame)
+          : null,
+      }),
     );
   }
 
@@ -1127,12 +1180,9 @@ async function performInteraction(
         );
     }
   } catch (error) {
-    const candidates = await collectInteractiveLabels(frame);
-    const candidateList =
-      candidates.length > 0 ? candidates.join(", ") : "(none found on page)";
     throw new Error(
       `preview-interact: action "${action}" failed against ${targetDesc}: ${error.message || String(error)}. ` +
-        `Candidate interactive labels: ${candidateList}`,
+        `Candidate interactive labels: ${await candidateLabelSummary(frame)}`,
     );
   }
 }
@@ -1209,6 +1259,7 @@ async function performInteractionSequence(
 
 module.exports = {
   logCaptureTiming,
+  defaultReadServerState,
   resolveTcpTarget,
   assertAppPortReachable,
   escapeHtmlAttribute,
@@ -1230,6 +1281,8 @@ module.exports = {
   loadScenarioInIframe,
   loadScenarioTopLevel,
   collectInteractiveLabels,
+  candidateLabelSummary,
+  noMatchGuidance,
   describeMatchCandidates,
   performInteraction,
   waitForPredicate,

package/npm/utils.js

@@ -5,7 +5,23 @@ const fs = require("fs");
 const readline = require("readline");
 
 const rootDir = path.resolve(__dirname, "..");
-const serverStatePath = path.join(rootDir, ".codeyam", "server-state.json");
+
+/**
+ * Path to the server-state file for `projectDir`.
+ *
+ * The editor server writes its state into the PROJECT it serves, not into the
+ * editor repo — so this must be resolved against the target project. It was
+ * previously a module-level const bound to `rootDir`, which made
+ * `readServerState` return `null` for every external-project launch and left
+ * the pid-based recovery in `stopServer` dead in exactly the configuration
+ * `codeyam-editor-dev` exists to serve.
+ *
+ * Defaults to `process.cwd()` because every in-repo caller already runs from
+ * the project root; external-project callers must pass their `projectDir`.
+ */
+function serverStatePathFor(projectDir = process.cwd()) {
+  return path.join(projectDir, ".codeyam", "server-state.json");
+}
 
 /**
  * Map (process.platform, process.arch) → the platform sub-package that
@@ -459,6 +475,56 @@ function resolveWrappedAppPort(merged, envValue, fallback) {
   return resolveLauncherPort(envValue, mergedValue, fallback);
 }
 
+/** True for a value usable as a TCP port: an integer in 1..=65535. */
+function isUsablePort(value) {
+  return Number.isInteger(value) && value > 0 && value <= 65535;
+}
+
+/**
+ * Resolve the control port a RUNNING server for `projectDir` is actually on.
+ *
+ * Mirrors `resolve_control_port` in
+ * `crates/codeyam-editor/src/commands/editor/control_port.rs`:
+ * `server-state.json` > `CODEYAM_CONTROL_PORT` > the config default. The
+ * editor server runs on a dynamic port whenever the Project Launcher or the
+ * desktop supervisor started it, and `editor.json`'s `proxy.controlPort` is
+ * only the static default — so `server-state.json` is the only reliable
+ * discriminator. The npm launchers used the INVERSE (config only, state file
+ * never consulted), which is why a `--restart` could target a port nothing was
+ * on while the live server sat on another.
+ *
+ * This resolves the port to SEARCH for, never the port to bind: the launcher
+ * deliberately binds the editor repo's own control port (see the comment at
+ * the `SERVER_PORT` resolution in `editor-dev.js`).
+ */
+function resolveRunningControlPort(projectDir = process.cwd(), configPort) {
+  const state = readServerState(projectDir);
+  if (state && isUsablePort(state.controlPort)) return state.controlPort;
+
+  const envValue = process.env.CODEYAM_CONTROL_PORT;
+  if (envValue !== undefined && envValue !== null && String(envValue).trim() !== "") {
+    const parsed = parseInt(String(envValue).trim(), 10);
+    if (isUsablePort(parsed)) return parsed;
+  }
+
+  return configPort;
+}
+
+/**
+ * Resolve the proxy HTTP port the server will bind for `projectDir`.
+ *
+ * Mirrors `resolve_proxy_http_port` in
+ * `crates/codeyam-editor/src/commands/start.rs`: `CODEYAM_PROXY_HTTP_PORT` >
+ * `proxy.httpPort` > 14100 (`default_http_port` in
+ * `crates/types/src/config.rs`). The start path binds this address
+ * unconditionally, so it is the port a second server actually collides on —
+ * the resource the control-port classification never looked at.
+ */
+function resolveProxyHttpPort(merged, envValue, fallback = 14100) {
+  const configured = merged && merged.proxy && merged.proxy.httpPort;
+  return resolveLauncherPort(envValue, configured, fallback);
+}
+
 /** Try to connect to a specific host:port. Returns true if something is listening. */
 function tryConnect(port, host) {
   return new Promise((resolve) => {
@@ -502,17 +568,17 @@ async function waitForPortToClose(port, timeoutMs = 10000, intervalMs = 200) {
   return false;
 }
 
-function readServerState() {
+function readServerState(projectDir = process.cwd()) {
   try {
-    return JSON.parse(fs.readFileSync(serverStatePath, "utf8"));
+    return JSON.parse(fs.readFileSync(serverStatePathFor(projectDir), "utf8"));
   } catch {
     return null;
   }
 }
 
-function clearServerState() {
+function clearServerState(projectDir = process.cwd()) {
   try {
-    fs.unlinkSync(serverStatePath);
+    fs.unlinkSync(serverStatePathFor(projectDir));
   } catch {}
 }
 
@@ -626,6 +692,100 @@ function formatCrossProjectError(port, holder, verb) {
   );
 }
 
+/**
+ * Build the "the proxy port this server must bind is already taken" error
+ * string. Lives next to the other `format*Error` builders so the wording is
+ * unit-testable without a running server. Names the port, the pid holding it,
+ * and the config key to change — the three things the old failure mode made
+ * the user dig out of `.codeyam/logs/editor-server.out.log` by hand.
+ */
+function formatProxyPortConflictError(httpPort, pids = []) {
+  const pidNote = pids.length > 0 ? ` (pid ${pids.join(", ")})` : "";
+  return (
+    `Port ${httpPort} is already in use${pidNote}, and the codeyam-editor ` +
+    `server binds it at startup — spawning now would fail with EADDRINUSE ` +
+    `and leave nothing listening.\n` +
+    `\n` +
+    `Free that port, or change httpPort in .codeyam/editor.local.json, e.g.:\n` +
+    `  codeyam-editor editor config-override proxy.httpPort ${httpPort + 100}`
+  );
+}
+
+/**
+ * Make sure the proxy HTTP port is free before a spawn that would bind it.
+ *
+ * The proxy port — not the control port — is the resource that actually
+ * conflicts: two servers for the same project legitimately resolve DIFFERENT
+ * control ports (the npm wrappers use the editor repo's config, the Rust binary
+ * uses the project's own), but both bind the project's `proxy.httpPort`. So a
+ * control-port classification can report "free" while the spawn is already
+ * doomed, which is exactly how a failed restart came to look like a successful
+ * one.
+ *
+ * Ownership is decided on the control port named by the project's own
+ * `server-state.json`, never by probing the identity endpoint through the proxy
+ * port itself: the proxy forwards to the wrapped app, so a probe there reports
+ * whatever the app answers and would misclassify this project's own server as
+ * foreign. Teardown likewise goes through the control port, where the shutdown
+ * endpoint lives.
+ *
+ * Returns `{ kind: "free" }`, `{ kind: "cleared" }` (a stale same-project server
+ * was stopped), or `{ kind: "conflict", pids }` — the caller owns the policy.
+ * Effects are injected so this is testable without a live server.
+ */
+async function ensureProxyPortAvailable(
+  httpPort,
+  projectDir = process.cwd(),
+  { classify = classifyPortHolder, stop = stopServer, isInUse = isPortInUse } = {},
+) {
+  if (!isUsablePort(httpPort) || !(await isInUse(httpPort))) {
+    return { kind: "free" };
+  }
+
+  const state = readServerState(projectDir);
+  const statePort = state && isUsablePort(state.controlPort) ? state.controlPort : null;
+  if (statePort !== null) {
+    const holder = await classify(statePort, projectDir);
+    if (holder.kind === "same-project") {
+      console.error(
+        `Port ${httpPort} is held by this project's own server on control ` +
+          `port ${statePort}; stopping it before starting a fresh one...`,
+      );
+      await stop(statePort, projectDir);
+      if (await waitForPortToClose(httpPort, 5000, 200)) {
+        return { kind: "cleared" };
+      }
+    }
+  }
+
+  return { kind: "conflict", pids: findListeningPids(httpPort) };
+}
+
+/**
+ * Build the "the launcher is not going to print a URL for a server that never
+ * came up" message, including the tail of the server output log.
+ *
+ * `tail` is the already-read log tail (see `readServerOutputLogTail`) or `null`
+ * when there was nothing readable — passed in rather than read here so the
+ * wording is testable without a filesystem, matching the other `format*Error`
+ * builders. The diagnostic was never missing from that log; it was written to a
+ * file nobody was told to read, which is why the tail is inlined into the
+ * message rather than merely pointed at.
+ */
+function formatLaunchFailureError(port, projectDir, tail = null) {
+  const logPath = path.join(projectDir, ".codeyam", "logs", "editor-server.out.log");
+  const head =
+    `Editor server is not listening on port ${port} — not printing a URL ` +
+    `that would refuse the connection.`;
+  if (tail === null) {
+    return (
+      `${head}\n\nNo readable ${logPath}; also check ` +
+      `${path.join(projectDir, ".codeyam", "logs", "editor-server.log")}.`
+    );
+  }
+  return `${head}\n\n--- tail of ${logPath} ---\n${tail}\n--- end of log tail ---`;
+}
+
 /**
  * Build the "server never bound the port" failure message, shown only after
  * the boot budget AND one automatic retry have both been exhausted. Pure
@@ -833,6 +993,47 @@ function openServerOutputLog(cwd) {
   }
 }
 
+/**
+ * Last `lines` non-empty-trailing lines of the launcher-managed server output
+ * log for `projectDir`, or `null` when there is nothing readable there.
+ *
+ * The diagnostic text for a failed launch was never missing — the exact
+ * `codeyam-editor cannot bind 127.0.0.1:<port>` line sat in this file the whole
+ * time. It was written to a file nobody was told to read, so the launcher
+ * surfaces the tail itself rather than printing a URL and exiting 0.
+ *
+ * Reads at most the trailing 64 KiB so a long-lived append-only log never costs
+ * a full file read. Best-effort by design: a missing or unreadable log degrades
+ * to `null`, never to a throw on the failure path.
+ */
+function readServerOutputLogTail(projectDir = process.cwd(), lines = 40) {
+  const MAX_TAIL_BYTES = 64 * 1024;
+  let fd = null;
+  try {
+    const logPath = path.join(projectDir, ".codeyam", "logs", "editor-server.out.log");
+    fd = fs.openSync(logPath, "r");
+    const size = fs.fstatSync(fd).size;
+    const length = Math.min(size, MAX_TAIL_BYTES);
+    if (length === 0) return null;
+    const buf = Buffer.alloc(length);
+    fs.readSync(fd, buf, 0, length, size - length);
+    const all = buf.toString("utf8").split("\n");
+    while (all.length > 0 && all[all.length - 1].trim() === "") all.pop();
+    if (all.length === 0) return null;
+    return all.slice(-lines).join("\n");
+  } catch {
+    return null;
+  } finally {
+    if (fd !== null) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        /* best-effort close on a diagnostic-only read */
+      }
+    }
+  }
+}
+
 /**
  * Format one launcher-teardown-signal record for
  * `.codeyam/logs/launcher-signals.log`. Pure: every input is passed in, so the
@@ -965,23 +1166,23 @@ function findListeningPids(port, runLsof = defaultRunLsof, sleep = sleepSync) {
 }
 
 /** Stop the Rust backend server if it is running. */
-async function stopServer(port = 14199) {
+async function stopServer(port = 14199, projectDir = process.cwd()) {
   if (!(await isPortInUse(port))) {
-    clearServerState();
+    clearServerState(projectDir);
     return false;
   }
 
   if (await requestServerShutdown(port)) {
     if (await waitForPortToClose(port, 10000, 200)) {
-      clearServerState();
+      clearServerState(projectDir);
       return true;
     }
   }
 
-  const state = readServerState();
+  const state = readServerState(projectDir);
   if (state && Number.isInteger(state.pid) && tryKillPid(state.pid)) {
     if (await waitForPortToClose(port, 5000, 200)) {
-      clearServerState();
+      clearServerState(projectDir);
       return true;
     }
   }
@@ -991,20 +1192,37 @@ async function stopServer(port = 14199) {
   }
 
   if (await waitForPortToClose(port, 5000, 200)) {
-    clearServerState();
+    clearServerState(projectDir);
     return true;
   }
 
   throw new Error(`Server on port ${port} did not stop cleanly`);
 }
 
-/** Stop any existing server on the port, then start a fresh one. */
-async function restartServer(port = 14199) {
-  if (await isPortInUse(port)) {
-    console.error(`Stopping existing server on port ${port}...`);
-    await stopServer(port);
+/**
+ * Stop any existing server for this project, then start a fresh one on `port`.
+ *
+ * `port` is the port to BIND (owned by the editor repo's merged config); the
+ * port to TEAR DOWN is resolved separately via `resolveRunningControlPort`,
+ * because a server started outside the npm wrapper records a different, live
+ * control port in the project's `server-state.json`. Gating teardown on `port`
+ * alone is what let a stale server survive a restart and kill the relaunch with
+ * EADDRINUSE on the proxy port. Both are torn down (deduped) so the restart's
+ * historical guarantee — nothing left on the port we are about to bind — holds
+ * whichever port the live server turned out to be on.
+ */
+async function restartServer(port = 14199, projectDir = process.cwd()) {
+  const runningPort = resolveRunningControlPort(projectDir, port);
+  const seen = new Set();
+  for (const candidate of [runningPort, port]) {
+    if (!isUsablePort(candidate) || seen.has(candidate)) continue;
+    seen.add(candidate);
+    if (await isPortInUse(candidate)) {
+      console.error(`Stopping existing server on port ${candidate}...`);
+      await stopServer(candidate, projectDir);
+    }
   }
-  return ensureServer(port);
+  return ensureServer(port, projectDir);
 }
 
 /**
@@ -1016,8 +1234,8 @@ async function restartServer(port = 14199) {
  * mismatch — silently choosing a different port would just relocate the
  * surprise.
  */
-async function ensureServer(port = 14199) {
-  const holder = await classifyPortHolder(port);
+async function ensureServer(port = 14199, projectDir = process.cwd()) {
+  const holder = await classifyPortHolder(port, projectDir);
   switch (holder.kind) {
     case "foreign":
       console.error(formatForeignListenerError(port));
@@ -1056,6 +1274,21 @@ async function ensureServer(port = 14199) {
       break;
   }
 
+  // The control port is free (or was just taken over), but that is not the port
+  // the spawn is most likely to die on. `start.rs` binds `proxy.httpPort`
+  // unconditionally, so a holder there is a guaranteed EADDRINUSE — knowable
+  // with one probe here, and previously discovered only by reading a log after
+  // a silent failure.
+  const proxyHttpPort = resolveProxyHttpPort(
+    readMergedEditorConfig(projectDir),
+    process.env.CODEYAM_PROXY_HTTP_PORT,
+  );
+  const proxyPort = await ensureProxyPortAvailable(proxyHttpPort, projectDir);
+  if (proxyPort.kind === "conflict") {
+    console.error(formatProxyPortConflictError(proxyHttpPort, proxyPort.pids));
+    process.exit(1);
+  }
+
   const binary = ensureBinary();
   const startTimeoutMs = resolveStartTimeoutMs();
 
@@ -1075,12 +1308,12 @@ async function ensureServer(port = 14199) {
   // editor-server.log). `unref()` keeps the detached child from pinning the
   // launcher's event loop alive on its own.
   const spawnAndAwait = async (timeoutMs) => {
-    const logFd = openServerOutputLog(process.cwd());
+    const logFd = openServerOutputLog(projectDir);
     const child = spawn(
       binary,
       ["start", "--no-open", "--port", String(port)],
       buildServerSpawnOptions({
-        cwd: process.cwd(),
+        cwd: projectDir,
         env: serverSpawnEnv(process.env, { devCheckout: isDevCheckout() }),
         logFd,
       }),
@@ -1215,7 +1448,7 @@ async function awaitServerReadyOrChildExit(child, port, waitForPortFn = waitForP
 
 module.exports = {
   rootDir,
-  serverStatePath,
+  serverStatePathFor,
   binaryName,
   brokerBinaryName,
   platformPackageInfo,
@@ -1241,6 +1474,9 @@ module.exports = {
   classifyPortHolder,
   formatForeignListenerError,
   formatCrossProjectError,
+  formatProxyPortConflictError,
+  formatLaunchFailureError,
+  ensureProxyPortAvailable,
   formatServerStartTimeoutError,
   resolveStartTimeoutMs,
   tryKillPid,
@@ -1264,4 +1500,8 @@ module.exports = {
   readMergedEditorConfig,
   resolveLauncherPort,
   resolveWrappedAppPort,
+  resolveRunningControlPort,
+  resolveProxyHttpPort,
+  isUsablePort,
+  readServerOutputLogTail,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codeyam-editor/codeyam-editor",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "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.8",
-    "@codeyam-editor/codeyam-editor-darwin-x64": "0.1.8",
-    "@codeyam-editor/codeyam-editor-linux-x64": "0.1.8",
-    "@codeyam-editor/codeyam-editor-win32-x64": "0.1.8"
+    "@codeyam-editor/codeyam-editor-darwin-arm64": "0.1.9",
+    "@codeyam-editor/codeyam-editor-darwin-x64": "0.1.9",
+    "@codeyam-editor/codeyam-editor-linux-x64": "0.1.9",
+    "@codeyam-editor/codeyam-editor-win32-x64": "0.1.9"
   },
   "keywords": [
     "codeyam",