openship 0.4.5 → 0.4.7

package/dist/{chunk-XRWV5ZNR.js → chunk-FXTBHTWY.js}

@@ -1,8 +1,10 @@
+#!/usr/bin/env sh
+":" //# ; exec "$(command -v bun || command -v node)" "$0" "$@"
 import { createRequire as __ospCreateRequire } from "node:module";
 const require = __ospCreateRequire(import.meta.url);
 import {
   sq
-} from "./chunk-Z6EKX6CX.js";
+} from "./chunk-FPRHYBY2.js";
 import {
   ACME_CHALLENGE_LOCATION,
   ACME_HTTP01_PORT,
@@ -11,12 +13,12 @@ import {
   buildReloadCommand,
   detectOpenRestyPaths,
   luaSourceAvailable
-} from "./chunk-RZPDJC2J.js";
+} from "./chunk-VFINNTUL.js";
 import {
   PROXY_GZIP_TYPES,
   safeErrorMessage,
   sanitizeProxySettings
-} from "./chunk-3LCRNQ2C.js";
+} from "./chunk-6APULWSU.js";
 
 // ../../packages/adapters/src/infra/nginx.ts
 import {
@@ -25,12 +27,227 @@ import {
   rm as fsRm,
   mkdir as fsMkdir,
   readFile as fsReadFile,
-  rename as fsRename
+  rename as fsRename,
+  stat as fsStat
 } from "fs/promises";
 import { execFile as cpExecFile } from "child_process";
-import { randomBytes, X509Certificate, createPrivateKey } from "crypto";
+import { randomBytes } from "crypto";
 import { promisify } from "util";
 import { dirname, join } from "path";
+
+// ../../packages/adapters/src/system/proxy/cert-material.ts
+import { X509Certificate, createPrivateKey } from "crypto";
+
+// ../../packages/adapters/src/system/edge-container-executor.ts
+function containerCommand(container, command) {
+  return `docker exec ${sq(container)} sh -c ${sq(command)}`;
+}
+function resolveRef(ref) {
+  return typeof ref === "function" ? ref() : ref;
+}
+async function readMaybeInContainer(exec, path, container) {
+  const direct = await exec.readFile(path).catch(() => "");
+  if (direct.trim()) return direct;
+  const name = await resolveRef(container);
+  if (!name) return "";
+  return exec.exec(containerCommand(name, `cat ${sq(path)}`)).catch(() => "");
+}
+async function writeEdgeFileIn(inner, container, path, content) {
+  await inner.writeFile(path, content);
+  if (!container) return;
+  const visible = await inner.exec(containerCommand(container, `test -e ${sq(path)} && echo visible`)).catch(() => "");
+  if (visible.trim() === "visible") return;
+  const dir = path.replace(/\/[^/]*$/, "");
+  if (dir && dir !== path) {
+    await inner.exec(containerCommand(container, `mkdir -p ${sq(dir)}`)).catch(() => {
+    });
+  }
+  await inner.exec(`docker cp ${sq(path)} ${sq(`${container}:${path}`)}`).catch(() => {
+  });
+}
+function edgeContainerExecutor(inner, container, opts) {
+  const inContainer = (command) => containerCommand(container, command);
+  const overrides = {
+    exec: (command, execOpts) => inner.exec(inContainer(command), execOpts),
+    streamExec: (command, onLog) => inner.streamExec(inContainer(command), onLog),
+    // A rename is a FILE op, so it follows the files, never the commands. Stated
+    // here rather than left to the Proxy's passthrough: if the inner executor has no
+    // `rename`, the fallback must still be the INNER shell (the host) — routing it
+    // through this decorator's `exec` would put a `mv` inside the container, where
+    // the host path it was handed does not exist.
+    rename: async (from, to) => {
+      if (inner.rename) return inner.rename(from, to);
+      await inner.exec(`mv ${sq(from)} ${sq(to)}`);
+    }
+  };
+  if (opts?.files === "auto") {
+    Object.assign(overrides, {
+      readFile: (path) => readMaybeInContainer(inner, path, container),
+      writeFile: (path, content) => writeEdgeFileIn(inner, container, path, content),
+      exists: async (path) => {
+        if (await inner.exists(path).catch(() => false)) return true;
+        const { code } = await inner.streamExec(inContainer(`test -e ${sq(path)}`), () => {
+        });
+        return code === 0;
+      },
+      // The rename half of an atomic write must land in the same namespace as the
+      // write itself, so it follows readFile/writeFile — host first, container only
+      // when the host can't see the file.
+      rename: async (from, to) => {
+        if (await inner.exists(from).catch(() => false)) {
+          if (inner.rename) return inner.rename(from, to);
+          await inner.exec(`mv ${sq(from)} ${sq(to)}`);
+          return;
+        }
+        await inner.exec(inContainer(`mv ${sq(from)} ${sq(to)}`));
+      },
+      // mkdir/rm are idempotent and rare (route register/deregister), so both homes
+      // get them unconditionally rather than paying a probe to decide.
+      mkdir: async (path) => {
+        await inner.mkdir(path);
+        await inner.exec(inContainer(`mkdir -p ${sq(path)}`)).catch(() => {
+        });
+      },
+      rm: async (path) => {
+        await inner.rm(path);
+        await inner.exec(inContainer(`rm -rf ${sq(path)}`)).catch(() => {
+        });
+      }
+    });
+  }
+  return new Proxy(inner, {
+    get(target, prop) {
+      if (Object.prototype.hasOwnProperty.call(overrides, prop)) {
+        return overrides[prop];
+      }
+      const value = Reflect.get(target, prop, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    }
+  });
+}
+
+// ../../packages/adapters/src/system/proxy/cert-material.ts
+var ACME_ISSUERS = [
+  "let's encrypt",
+  "lets encrypt",
+  "letsencrypt",
+  "zerossl",
+  "google trust services",
+  "buypass",
+  "actalis",
+  "ssl.com"
+];
+function issuerLabel(x509) {
+  const fields = /* @__PURE__ */ new Map();
+  for (const line of x509.issuer.split("\n")) {
+    const eq = line.indexOf("=");
+    if (eq > 0) fields.set(line.slice(0, eq).trim().toUpperCase(), line.slice(eq + 1).trim());
+  }
+  return fields.get("CN") ?? fields.get("O") ?? x509.issuer.replace(/\n/g, ", ");
+}
+function isAcmeIssuer(x509) {
+  const haystack = `${x509.issuer}`.toLowerCase();
+  return ACME_ISSUERS.some((ca) => haystack.includes(ca));
+}
+function certNames(x509) {
+  const names = [];
+  for (const entry of (x509.subjectAltName ?? "").split(",")) {
+    const [kind, ...rest] = entry.trim().split(":");
+    if (kind?.toUpperCase() === "DNS" && rest.length) names.push(rest.join(":").trim().toLowerCase());
+  }
+  if (names.length === 0) {
+    const cn = x509.subject.split("\n").find((l) => l.trim().toUpperCase().startsWith("CN="));
+    if (cn) names.push(cn.slice(cn.indexOf("=") + 1).trim().toLowerCase());
+  }
+  return names;
+}
+function coversHost(x509, host) {
+  const target = host.toLowerCase();
+  if (x509.checkHost(target)) return true;
+  return certNames(x509).some((name) => {
+    if (name === target) return true;
+    if (!name.startsWith("*.")) return false;
+    const suffix = name.slice(1);
+    return target.endsWith(suffix) && !target.slice(0, -suffix.length).includes(".");
+  });
+}
+function validateCertFor(host, pems, source) {
+  const certPem = pems.certPem ?? "";
+  const keyPem = pems.keyPem ?? "";
+  if (!certPem.trim() || !keyPem.trim()) {
+    return { cert: null, reason: `${source}: cert or key is empty` };
+  }
+  let x509;
+  try {
+    x509 = new X509Certificate(certPem);
+  } catch (err) {
+    return { cert: null, reason: `${source}: unreadable certificate (${safeErrorMessage(err)})` };
+  }
+  try {
+    if (!x509.checkPrivateKey(createPrivateKey(keyPem))) {
+      return { cert: null, reason: `${source}: private key does not match the certificate` };
+    }
+  } catch (err) {
+    return { cert: null, reason: `${source}: unreadable private key (${safeErrorMessage(err)})` };
+  }
+  if (!coversHost(x509, host)) {
+    return {
+      cert: null,
+      reason: `${source}: certificate covers ${certNames(x509).join(", ") || "no DNS names"} \u2014 not ${host}`
+    };
+  }
+  const notAfter = new Date(x509.validTo);
+  if (!Number.isFinite(notAfter.getTime())) {
+    return { cert: null, reason: `${source}: certificate has an unreadable expiry` };
+  }
+  if (notAfter.getTime() <= Date.now()) {
+    return { cert: null, reason: `${source}: certificate expired ${notAfter.toISOString()}` };
+  }
+  return {
+    cert: {
+      certPem,
+      keyPem,
+      source,
+      expiresAt: notAfter.toISOString(),
+      issuer: issuerLabel(x509),
+      covers: certNames(x509),
+      renewable: isAcmeIssuer(x509)
+    }
+  };
+}
+function isSafeCertPath(p) {
+  return /^\/[A-Za-z0-9._/-]+$/.test(p) && !p.includes("..");
+}
+async function readDeclaredPair(exec, certPath, keyPath, container) {
+  if (!isSafeCertPath(certPath) || !isSafeCertPath(keyPath)) return null;
+  const certPem = await readMaybeInContainer(exec, certPath, container);
+  const keyPem = await readMaybeInContainer(exec, keyPath, container);
+  return certPem && keyPem ? { certPem, keyPem } : null;
+}
+
+// ../../packages/adapters/src/system/output-exists.ts
+function buildCommand(servedPath) {
+  const p = servedPath.replace(/'/g, "'\\''");
+  return [
+    `if [ -e '${p}' ]; then echo FOUND; fi`,
+    `if [ -f '${p}' ] || [ -f '${p}/index.html' ]; then echo INDEX; fi`,
+    "true"
+  ].join("; ");
+}
+async function probeStaticOutput(executor, servedPath) {
+  try {
+    const out = await executor.exec(buildCommand(servedPath), { timeout: 5e3 });
+    return {
+      found: /(^|\n)FOUND(\r?\n|$)/.test(out),
+      hasIndex: /(^|\n)INDEX(\r?\n|$)/.test(out),
+      checked: true
+    };
+  } catch {
+    return { found: false, hasIndex: false, checked: false };
+  }
+}
+
+// ../../packages/adapters/src/infra/nginx.ts
 var PROXY_HEADERS = `proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
@@ -118,11 +335,19 @@ function assertValidUpstream(targetUrl) {
     throw new Error(`Invalid proxy target (must be http/https URL): ${targetUrl}`);
   }
 }
-function assertValidStaticRoot(root) {
+var MANAGED_STATIC_BASE = "/opt/openship";
+function assertValidStaticRoot(root, opts) {
   assertNoNginxInjection(root, "static root");
   if (!root.startsWith("/") || root.includes("..")) {
     throw new Error(`Invalid static root (must be an absolute path, no traversal): ${root}`);
   }
+  if (opts?.adopted) return;
+  const confined = root === MANAGED_STATIC_BASE || root.startsWith(`${MANAGED_STATIC_BASE}/`);
+  if (!confined) {
+    throw new Error(
+      `Refusing to serve static root outside ${MANAGED_STATIC_BASE}: ${root}. Openship-managed routes serve only their own build output; pass staticRootAdopted when importing a root an existing proxy already serves.`
+    );
+  }
 }
 var execFileAsync = promisify(cpExecFile);
 function summarizeCertbotFailure(output, domain) {
@@ -151,12 +376,14 @@ var NginxProvider = class {
   certDir;
   executor;
   reloadCommand;
+  pinPaths;
   constructor(opts) {
     this.sitesDir = opts.paths.sitesDir;
     this.acmeEmail = opts.acmeEmail;
     this.certDir = opts.certDir ?? DEFAULT_CERT_DIR;
     this.executor = opts.executor ?? null;
     this.reloadCommand = buildReloadCommand(opts.paths);
+    this.pinPaths = opts.pinPaths ?? false;
   }
   // ── File operation helpers (dual-path: local or remote) ──────────────
   async _writeFile(path, content) {
@@ -164,7 +391,11 @@ var NginxProvider = class {
     if (this.executor) {
       try {
         await this.executor.writeFile(tmpPath, content);
-        await this.executor.exec(`mv ${sq(tmpPath)} ${sq(path)}`);
+        if (this.executor.rename) {
+          await this.executor.rename(tmpPath, path);
+        } else {
+          await this.executor.exec(`mv ${sq(tmpPath)} ${sq(path)}`);
+        }
       } catch (err) {
         await this.executor.rm(tmpPath).catch(() => void 0);
         throw err;
@@ -214,6 +445,37 @@ var NginxProvider = class {
       await fsMkdir(path, { recursive: true });
     }
   }
+  /**
+   * Put `fullchain.pem` + `privkey.pem` in `dir` as ONE atomic step.
+   *
+   * Both files are written into a temp sibling dir, then the pair is moved into
+   * place together. A cert and its key are only valid as a set — writing them
+   * individually means a crash, a full disk, or a dropped SSH connection between
+   * the two leaves the new cert next to the previous key, and `openresty -t` then
+   * fails for the WHOLE edge (every domain, not just this one) until someone
+   * notices. `mv -T`/rename of the staged dir also means a concurrent reload sees
+   * either the old pair or the new one, never a half-written PEM.
+   */
+  async stageCertDir(dir, cert) {
+    const staging = `${dir}.staging-${process.pid}-${randomBytes(4).toString("hex")}`;
+    try {
+      await this._mkdir(staging);
+      await this._writeFile(join(staging, "fullchain.pem"), cert.certPem);
+      await this._writeFile(join(staging, "privkey.pem"), cert.keyPem);
+      if (this.executor) {
+        await this._mkdir(dir);
+        await this.executor.exec(
+          `mv -f ${sq(join(staging, "fullchain.pem"))} ${sq(join(staging, "privkey.pem"))} ${sq(dir)}/`
+        );
+      } else {
+        await fsMkdir(dir, { recursive: true });
+        await fsRename(join(staging, "fullchain.pem"), join(dir, "fullchain.pem"));
+        await fsRename(join(staging, "privkey.pem"), join(dir, "privkey.pem"));
+      }
+    } finally {
+      await this._rm(staging).catch(() => void 0);
+    }
+  }
   async _exec(command, args = []) {
     if (this.executor) {
       const full = args.length ? `${command} ${args.map(sq).join(" ")}` : command;
@@ -228,6 +490,28 @@ var NginxProvider = class {
       throw new Error(detail || e.message || String(err));
     }
   }
+  /**
+   * Does this static `root` resolve where OpenResty looks? (RoutingProvider)
+   *
+   * Runs the probe through `this.executor` — the SAME handle vhost writes and
+   * `openresty -s reload` go through — so it answers from the edge's own vantage
+   * point. That is the whole value: for a containerized edge the executor's `exec`
+   * lands INSIDE the container (DockerEdgeExecutor / edgeContainerExecutor), so a
+   * `root` that exists on the host but was never bind-mounted reads as missing
+   * here, which is exactly the 404 a host-side probe cannot see. With no executor
+   * the edge is bare-local and shares this process's filesystem, so node:fs is
+   * already the right vantage point.
+   *
+   * Advisory: never throws.
+   */
+  async probeStaticRoot(servedPath) {
+    if (this.executor) return probeStaticOutput(this.executor, servedPath);
+    const found = await this._exists(servedPath);
+    if (!found) return { found: false, hasIndex: false, checked: true };
+    const isFile = await fsStat(servedPath).then((s) => s.isFile()).catch(() => false);
+    const hasIndex = isFile || await this._exists(join(servedPath, "index.html"));
+    return { found: true, hasIndex, checked: true };
+  }
   /**
    * Run certbot, optionally STREAMING its output line-by-line to `onLog` (the
    * live verify modal). Falls back to buffered `_exec` when no callback / no
@@ -281,7 +565,7 @@ var NginxProvider = class {
     const slug = this.domainSlug(route.domain);
     const configPath = join(this.sitesDir, `${slug}.conf`);
     if ("staticRoot" in route && route.staticRoot) {
-      assertValidStaticRoot(route.staticRoot);
+      assertValidStaticRoot(route.staticRoot, { adopted: route.staticRootAdopted });
     } else {
       assertValidUpstream(route.targetUrl);
     }
@@ -459,7 +743,12 @@ ${webhookLocation}${extraLocations}
       }
       const rootMatch = existing.match(/root\s+([^;]+);/);
       if (rootMatch) {
-        await this.registerRoute({ domain, staticRoot: rootMatch[1], tls: true });
+        await this.registerRoute({
+          domain,
+          staticRoot: rootMatch[1],
+          staticRootAdopted: true,
+          tls: true
+        });
         return this.ensureIssued(domain, certonlyOut);
       }
     } catch {
@@ -492,32 +781,41 @@ ${tail}` : "")
     if (!await this.certsExist(domain)) {
       return this.provisionCert(domain);
     }
+    if (!await this.hasCertbotLineage(domain)) {
+      return this.provisionCert(domain, { force: true });
+    }
     await this._exec("certbot", ["renew", "--cert-name", domain, "--non-interactive"]);
     await this.reload();
     return this.readCertInfo(domain);
   }
   /**
-   * Install an operator-supplied certificate (no ACME). Validates the PEM pair,
-   * writes it to the same on-disk path certbot uses, then re-registers the vhost
-   * with TLS — mirroring provisionCert's tail so composite routes are preserved.
+   * Does certbot track a renewal lineage for this domain? `/etc/letsencrypt/renewal/
+   * <domain>.conf` is the per-lineage record certbot writes on first issuance and
+   * reads on every `renew`, so its presence is the authoritative answer — the cert
+   * FILES existing is not (they can be adopted, or copied in by hand).
+   */
+  async hasCertbotLineage(domain) {
+    const renewalPath = join(dirname(this.certDir), "renewal", `${domain}.conf`);
+    return this._exists(renewalPath);
+  }
+  /**
+   * Install an operator-supplied or adopted certificate (no ACME). Validates the
+   * PEM pair against the domain, writes it to the same on-disk path certbot uses,
+   * then re-registers the vhost with TLS — mirroring provisionCert's tail so
+   * composite routes are preserved.
+   *
+   * The validation is deliberately here, at the last gate before disk, and not
+   * only in the callers: every path that puts a cert on this box (operator upload,
+   * migration carry, cert reuse) funnels through this method, so a check here can't
+   * be bypassed by a new caller that forgets it.
    */
   async installCert(domain, cert) {
     assertValidDomain(domain);
-    let expiresAt;
-    try {
-      const x509 = new X509Certificate(cert.certPem);
-      const key = createPrivateKey(cert.keyPem);
-      if (!x509.checkPrivateKey(key)) {
-        throw new Error("private key does not match certificate");
-      }
-      expiresAt = new Date(x509.validTo).toISOString();
-    } catch (err) {
-      throw new Error(`Invalid certificate: ${safeErrorMessage(err)}`);
-    }
+    const candidate = validateCertFor(domain, cert, "supplied certificate");
+    if (!candidate.cert) throw new Error(`Invalid certificate: ${candidate.reason}`);
+    const { expiresAt } = candidate.cert;
     const dir = join(this.certDir, domain);
-    await this._mkdir(dir);
-    await this._writeFile(join(dir, "fullchain.pem"), cert.certPem);
-    await this._writeFile(join(dir, "privkey.pem"), cert.keyPem);
+    await this.stageCertDir(dir, cert);
     const slug = this.domainSlug(domain);
     try {
       const state = await this._readFile(this.routeStatePath(slug));
@@ -525,7 +823,13 @@ ${tail}` : "")
       await this.registerRoute({ ...saved, domain, tls: true });
     } catch {
     }
-    return { domain, expiresAt, issuer: "manual", verified: true, reason: "issued" };
+    return {
+      domain,
+      expiresAt,
+      issuer: candidate.cert.renewable ? candidate.cert.issuer : "manual",
+      verified: true,
+      reason: "issued"
+    };
   }
   // ── Helpers ──────────────────────────────────────────────────────────
   domainSlug(domain) {
@@ -540,11 +844,13 @@ ${tail}` : "")
    */
   async reload() {
     if (this.executor) {
-      try {
-        const freshPaths = await detectOpenRestyPaths(this.executor);
-        this.sitesDir = freshPaths.sitesDir;
-        this.reloadCommand = buildReloadCommand(freshPaths);
-      } catch {
+      if (!this.pinPaths) {
+        try {
+          const freshPaths = await detectOpenRestyPaths(this.executor);
+          this.sitesDir = freshPaths.sitesDir;
+          this.reloadCommand = buildReloadCommand(freshPaths);
+        } catch {
+        }
       }
       await this.executor.exec(this.reloadCommand);
       return;
@@ -574,20 +880,25 @@ ${tail}` : "")
     if (!await this.certsExist(domain)) {
       return { domain, expiresAt: "", issuer: "certbot", verified: false, reason: "missing" };
     }
+    let certPem;
+    let keyPem;
     try {
-      const certPath = join(this.certDir, domain, "fullchain.pem");
-      const pem = await this._readFile(certPath);
-      const { X509Certificate: X509Certificate2 } = await import("crypto");
-      const cert = new X509Certificate2(pem);
-      return {
-        domain,
-        expiresAt: new Date(cert.validTo).toISOString(),
-        issuer: "certbot",
-        verified: true
-      };
+      certPem = await this._readFile(join(this.certDir, domain, "fullchain.pem"));
+      keyPem = await this._readFile(join(this.certDir, domain, "privkey.pem"));
     } catch {
       return { domain, expiresAt: "", issuer: "certbot", verified: false, reason: "read_error" };
     }
+    const candidate = validateCertFor(domain, { certPem, keyPem }, "on-disk certificate");
+    if (!candidate.cert) {
+      console.warn(`[SSL] unusable cert on disk for ${domain}: ${candidate.reason}`);
+      return { domain, expiresAt: "", issuer: "certbot", verified: false, reason: "invalid" };
+    }
+    return {
+      domain,
+      expiresAt: candidate.cert.expiresAt,
+      issuer: candidate.cert.issuer || "certbot",
+      verified: true
+    };
   }
   /**
    * Read-only check that the Let's Encrypt cert is actually present + valid on
@@ -741,8 +1052,15 @@ ${geoEntries.join("\n")}
 };
 
 export {
+  containerCommand,
+  readMaybeInContainer,
+  edgeContainerExecutor,
+  validateCertFor,
+  isSafeCertPath,
+  readDeclaredPair,
   renderProxyOptions,
   renderGeoEntries,
+  MANAGED_STATIC_BASE,
   summarizeCertbotFailure,
   NginxProvider
 };

package/dist/chunk-ILFETZOM.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env sh
+":" //# ; exec "$(command -v bun || command -v node)" "$0" "$@"
+import { createRequire as __ospCreateRequire } from "node:module";
+const require = __ospCreateRequire(import.meta.url);
+
+// ../../packages/adapters/src/system/port-listen.ts
+var PROC_NET_TCP_CMD = "cat /proc/net/tcp 2>/dev/null; cat /proc/net/tcp6 2>/dev/null; true";
+var TCP_LISTEN = "0A";
+function parseListeningPorts(procText) {
+  const ports = /* @__PURE__ */ new Set();
+  for (const rawLine of procText.split("\n")) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    const fields = line.split(/\s+/);
+    if (fields.length < 4) continue;
+    if (fields[3] !== TCP_LISTEN) continue;
+    const local = fields[1];
+    const colon = local.lastIndexOf(":");
+    if (colon === -1) continue;
+    const hexPort = local.slice(colon + 1);
+    if (!/^[0-9A-Fa-f]{1,4}$/.test(hexPort)) continue;
+    const port = parseInt(hexPort, 16);
+    if (port > 0) ports.add(port);
+  }
+  return ports;
+}
+async function probePortListeningOnce(executor, port) {
+  try {
+    const out = await executor.exec(PROC_NET_TCP_CMD, { timeout: 5e3 });
+    return parseListeningPorts(out).has(port);
+  } catch {
+    return null;
+  }
+}
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function waitForPortListening(executor, port, opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? 45e3;
+  const intervalMs = opts.intervalMs ?? 1e3;
+  const deadline = Date.now() + timeoutMs;
+  let anyConclusive = false;
+  try {
+    for (; ; ) {
+      const result = await probePortListeningOnce(executor, port);
+      if (result === true) return { listening: true, checked: true };
+      if (result === false) anyConclusive = true;
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) break;
+      await delay(Math.min(intervalMs, remaining));
+    }
+  } catch {
+    return { listening: false, checked: false };
+  }
+  return anyConclusive ? { listening: false, checked: true } : { listening: false, checked: false };
+}
+
+// ../../packages/adapters/src/runtime/port-conflict.ts
+async function tryExec(executor, command) {
+  try {
+    return await executor.exec(command);
+  } catch {
+    return null;
+  }
+}
+async function resolveSystemdUnit(executor, pid) {
+  const cgroup = await tryExec(executor, `cat /proc/${pid}/cgroup 2>/dev/null || true`);
+  const unitMatch = cgroup?.match(/(?:^|\/)([^/\n]+\.service)(?:$|\n|\/)/m) ?? cgroup?.match(/(?:^|\/)([^/\n]+\.service)(?:$|\n|\/)/m);
+  const systemdUnit = unitMatch?.[1]?.trim();
+  if (!systemdUnit || !/^[A-Za-z0-9@._:\\-]+\.service$/.test(systemdUnit)) {
+    return {};
+  }
+  const description = await tryExec(
+    executor,
+    `systemctl show ${systemdUnit} --property=Description --value 2>/dev/null || true`
+  );
+  const managedMatch = systemdUnit.match(/^openship-(.+)\.service$/);
+  return {
+    systemdUnit,
+    systemdDescription: description?.trim() || void 0,
+    deploymentId: managedMatch?.[1],
+    isManagedDeployment: Boolean(managedMatch)
+  };
+}
+async function resolveListener(executor, port) {
+  const out = await tryExec(
+    executor,
+    `ss -tlnp sport = :${port} 2>/dev/null | grep LISTEN || lsof -ti tcp:${port} -sTCP:LISTEN 2>/dev/null || true`
+  );
+  if (out) {
+    const ssMatch = out.match(/pid=(\d+)/);
+    const lsofMatch = !ssMatch ? out.match(/^\s*(\d+)\s*$/m) : null;
+    const pid = ssMatch ? parseInt(ssMatch[1], 10) : lsofMatch ? parseInt(lsofMatch[1], 10) : null;
+    if (pid) return { pid, occupied: true };
+  }
+  const listening = await probePortListeningOnce(executor, port);
+  return { pid: null, occupied: listening === true };
+}
+async function probeListeningPort(executor, port) {
+  try {
+    const { pid, occupied } = await resolveListener(executor, port);
+    if (!occupied) return null;
+    if (pid === null) return { pid: null, command: "unknown listener" };
+    return await describeProcess(executor, pid);
+  } catch {
+    return null;
+  }
+}
+async function describeProcess(executor, pid) {
+  let command = `PID ${pid}`;
+  let rawCommand;
+  const args = await tryExec(executor, `ps -p ${pid} -o args= 2>/dev/null || true`);
+  if (args?.trim()) {
+    rawCommand = args.trim();
+    command = `${rawCommand} (PID ${pid})`;
+  } else {
+    const cmd = await tryExec(executor, `ps -p ${pid} -o comm= 2>/dev/null || true`);
+    if (cmd?.trim()) {
+      rawCommand = cmd.trim();
+      command = `${rawCommand} (PID ${pid})`;
+    }
+  }
+  const systemd = await resolveSystemdUnit(executor, pid);
+  return { pid, command, rawCommand, ...systemd };
+}
+
+export {
+  waitForPortListening,
+  probeListeningPort,
+  describeProcess
+};