@mycadet/cli 0.12.10 → 0.13.0

package/src/lib/nginx-ingress.ts

@@ -13,9 +13,12 @@ import {
   rmSync,
   writeFileSync,
 } from "node:fs";
+import { createServer } from "node:net";
 import { networkInterfaces } from "node:os";
 import { join } from "node:path";
 
+import { z } from "zod";
+
 import { cloudAssistantHubUrl } from "@mycadet/environments";
 
 import {
@@ -27,7 +30,7 @@ import {
 } from "./assistant-config.js";
 import type { RemoteHost } from "./constants.js";
 import { getCurrentEnvironment } from "./environments/resolve.js";
-import { waitForDaemonReady } from "./http-client.js";
+import { fetchCurrentVersion, waitForDaemonReady } from "./http-client.js";
 import {
   getDefaultWorkspaceDir,
   isLocalContainerEntry,
@@ -35,7 +38,8 @@ import {
   parseGatewayPortFromEntryUrls,
   saveRawConfig,
 } from "./ingress-config.js";
-import { findWebDistDir } from "./web-dist.js";
+import { stripVersionPrefix } from "./version-compat.js";
+import { findWebDistDir, readWebReleaseVersion } from "./web-dist.js";
 
 export { findWebDistDir } from "./web-dist.js";
 
@@ -140,6 +144,8 @@ const DENYLIST_LOCATIONS = `    location = /auth/token { return 404; }
 export interface RemoteWebIngressOptions {
   webDistDir: string;
   indexHtmlPath?: string;
+  /** Assistant release verified against the served UI artifact. */
+  version?: string;
   config?: Record<string, unknown>;
   /** Serving assistant's display name, stamped into the served config so
    *  remote clients can label this origin. Absent in older served configs. */
@@ -149,24 +155,31 @@ export interface RemoteWebIngressOptions {
    *  configs. */
   assistantId?: string;
   /** Cloud web SPA base the remote client can hand this origin to (see
-   *  `cloudWebHubUrl`). Absent in older served configs. */
+   *  `cloudAssistantHubUrl`). Absent in older served configs. */
   hubUrl?: string;
 }
 
-/**
- * Cloud web SPA base URL for a build environment. The mapping lives in
- * `@mycadet/environments` (`cloudAssistantHubUrl`) and is shared with the
- * Capacitor shell's `server.url`, so the two consumers cannot drift.
- */
-export function cloudWebHubUrl(env: string | undefined): string {
-  return cloudAssistantHubUrl(env);
-}
-
 // The edge serves remote browsers, so the bundle's remote-gateway machinery
 // must always run: it is reached through this self-hosted edge however the
 // cadet itself is hosted. "cloud" is never stamped (the cloud serves its
 // own bundles).
-const EDGE_SERVED_REMOTE: RemoteHost = "custom";
+/** The lockfile's recorded remote kind for the assistant, if one is found. */
+function lockfileAssistantRemote(assistantId: string): string | undefined {
+  const result = lookupAssistantByIdentifier(assistantId);
+  return result.status === "found" ? result.entry.cloud : undefined;
+}
+
+/**
+ * The remote kind stamped into the served SPA config. Docker and custom
+ * cadets are stamped truthfully; every other hosting shape — a local cadet
+ * reached through this edge, paired remotes, unknown entries — reads as
+ * "custom" so the served bundle always runs the remote-gateway machinery
+ * (this edge serves remote browsers however the cadet itself is hosted).
+ * "cloud" is never stamped: the cloud serves its own bundles.
+ */
+export function edgeServedRemote(recorded: string | undefined): RemoteHost {
+  return recorded === "docker" ? "docker" : "custom";
+}
 
 function remoteWebIngressConfig(
   opts: Pick<
@@ -175,7 +188,9 @@ function remoteWebIngressConfig(
   >,
 ): Record<string, unknown> {
   return {
-    remote: EDGE_SERVED_REMOTE,
+    remote: edgeServedRemote(
+      opts.assistantId ? lockfileAssistantRemote(opts.assistantId) : undefined,
+    ),
     apiBaseUrl: "/v1",
     ...(opts.assistantName ? { assistantName: opts.assistantName } : {}),
     ...(opts.assistantId ? { assistantId: opts.assistantId } : {}),
@@ -189,17 +204,29 @@ function remoteWebIngressConfig(
  * fingerprint matches, so this must change whenever the generated index or
  * nginx template does.
  */
-export const EDGE_TEMPLATE_VERSION = 10;
+export const EDGE_TEMPLATE_VERSION = 12;
 
 /**
- * Stable fingerprint of the SPA config injected into the served index and
- * `/assistant/__config`, plus the template that renders them. Recorded
+ * Stable fingerprint of the injected SPA config, its source bundle, and
+ * the template that renders them. Recorded
  * alongside the edge state so a reuse decision can tell whether a running edge
  * already serves the requested config (see `IngressState.remoteWebConfigHash`).
  */
-function remoteWebConfigFingerprint(config: Record<string, unknown>): string {
+function remoteWebConfigFingerprint(
+  config: Record<string, unknown>,
+  webDistDir: string,
+  version?: string,
+): string {
   return createHash("sha256")
-    .update(JSON.stringify({ template: EDGE_TEMPLATE_VERSION, config }))
+    .update(
+      JSON.stringify({
+        template: EDGE_TEMPLATE_VERSION,
+        config,
+        webDistDir,
+        version,
+        indexHtml: readFileSync(join(webDistDir, "index.html"), "utf-8"),
+      }),
+    )
     .digest("hex");
 }
 
@@ -278,9 +305,138 @@ export function hasIpv6Loopback(): boolean {
     .some((addr) => addr.address === "::1");
 }
 
+/** Whether a TCP listener already holds `port` on the given loopback host. */
+async function isPortInUse(
+  port: number,
+  host: "127.0.0.1" | "::1",
+): Promise<boolean> {
+  return await new Promise((resolve) => {
+    const probe = createServer();
+    probe.once("error", () => resolve(true));
+    probe.once("listening", () => {
+      probe.close(() => resolve(false));
+    });
+    probe.listen(port, host);
+  });
+}
+
 /**
- * Build the nginx config that forwards tunnel web traffic to the gateway.
+ * The first free loopback port at or above `startPort`, scanning a short band,
+ * or null when the whole band is busy. Both stacks the edge may bind are
+ * probed (the IPv4 loopback always, the IPv6 loopback when the host has one),
+ * so the returned port is one nginx can actually take.
  */
+export async function findAvailableIngressPort(
+  startPort: number,
+  attempts = 20,
+): Promise<number | null> {
+  const checkIpv6 = hasIpv6Loopback();
+  for (let port = startPort; port < startPort + attempts; port++) {
+    if (await isPortInUse(port, "127.0.0.1")) {
+      continue;
+    }
+    if (checkIpv6 && (await isPortInUse(port, "::1"))) {
+      continue;
+    }
+    return port;
+  }
+  return null;
+}
+
+const AssistantHostConfigSchema = z.object({
+  assistantId: z.string().min(1).optional(),
+  assistantName: z.string().optional(),
+  version: z.string().min(1).optional(),
+  hubUrl: z.string().url().optional(),
+  appAllowedOrigins: z.array(z.string().url()).default([]),
+});
+
+function assistantHostConfig(config: Record<string, unknown>) {
+  const result = AssistantHostConfigSchema.safeParse(config);
+  if (!result.success) {
+    throw new Error("Invalid assistant host configuration.");
+  }
+  return result.data;
+}
+
+function appOrigins(config: Record<string, unknown>): string[] {
+  const metadata = assistantHostConfig(config);
+  const origins = [
+    ...metadata.appAllowedOrigins,
+    ...(metadata.hubUrl ? [new URL(metadata.hubUrl).origin] : []),
+  ];
+  return [...new Set(origins)].map((origin) => {
+    const url = new URL(origin);
+    if (
+      (url.protocol !== "https:" &&
+        !(
+          url.protocol === "http:" &&
+          ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)
+        )) ||
+      url.origin !== origin.replace(/\/$/, "")
+    ) {
+      throw new Error(
+        "App origins must be HTTPS origins or loopback HTTP origins.",
+      );
+    }
+    return url.origin;
+  });
+}
+
+function assistantMetadataLocations(config: Record<string, unknown>): string {
+  const metadata = assistantHostConfig(config);
+  const id = metadata.assistantId;
+  const choice = id
+    ? {
+        id,
+        ...(metadata.assistantName ? { name: metadata.assistantName } : {}),
+      }
+    : undefined;
+  const responses = [
+    {
+      path: "/v1/assistants",
+      status: 200,
+      body: { results: choice ? [choice] : [], next: null },
+    },
+    ...(choice && id
+      ? [
+          {
+            path: `/v1/assistants/${encodeURIComponent(id)}`,
+            status: metadata.version ? 200 : 409,
+            body: metadata.version
+              ? {
+                  ...choice,
+                  status: "active",
+                  version: metadata.version,
+                  url: "assistant/",
+                }
+              : { detail: "assistant is not ready" },
+          },
+        ]
+      : []),
+  ];
+  return responses
+    .flatMap(({ path, status, body }) =>
+      [path, `${path}/`].map(
+        (route) => `
+    location = ${nginxQuoted(route, "assistant API path")} {
+      default_type application/json;
+      add_header Cache-Control "no-store" always;
+      add_header Access-Control-Allow-Origin $cadet_app_origin always;
+      add_header Access-Control-Allow-Credentials "true" always;
+      add_header Access-Control-Allow-Methods "GET, HEAD, OPTIONS" always;
+      add_header Access-Control-Allow-Headers "Accept, Cadet-Organization-Id" always;
+      add_header Vary "Origin" always;
+      if ($request_method = OPTIONS) { return 204; }
+      if ($request_method !~ ^(GET|HEAD)$) { return 405; }
+      return ${status} ${nginxQuoted(JSON.stringify(body), "assistant metadata")};
+    }`,
+      ),
+    )
+    .join("\n");
+}
+
+/** Build the nginx config for the tunnel edge and its public assistant metadata. */
 export function buildIngressNginxConfig(opts: {
   gatewayPort: number;
   listenPort: number;
@@ -296,12 +452,16 @@ export function buildIngressNginxConfig(opts: {
     ? `    listen [::1]:${opts.listenPort};\n`
     : "";
   const remoteWebIngress = opts.remoteWebIngress;
+  const allowedOrigins = remoteWebIngress
+    ? appOrigins(remoteWebIngressConfig(remoteWebIngress))
+    : [];
   const serverLocations = remoteWebIngress
     ? buildRemoteWebIngressLocations({
         gatewayPort: opts.gatewayPort,
         webDistDir: remoteWebIngress.webDistDir,
         indexHtmlPath: remoteWebIngress.indexHtmlPath,
         config: remoteWebIngressConfig(remoteWebIngress),
+        version: remoteWebIngress.version,
       })
     : `${DENYLIST_LOCATIONS}
 
@@ -350,6 +510,11 @@ http {
     text/plain txt;
   }
 
+  map $http_origin $cadet_app_origin {
+    default "";
+${allowedOrigins.map((origin) => `    ${nginxQuoted(origin, "app origin")} ${nginxQuoted(origin, "app origin")};`).join("\n")}
+  }
+
   map $http_upgrade $connection_upgrade {
     default upgrade;
     "" close;
@@ -390,6 +555,7 @@ function buildRemoteWebIngressLocations(opts: {
   webDistDir: string;
   indexHtmlPath?: string;
   config: Record<string, unknown>;
+  version?: string;
 }): string {
   const proxyBlock = gatewayProxyBlock(opts.gatewayPort);
   const webDistDir = nginxDirPath(opts.webDistDir);
@@ -400,6 +566,8 @@ function buildRemoteWebIngressLocations(opts: {
 
   return `${DENYLIST_LOCATIONS}
 
+${assistantMetadataLocations({ ...opts.config, version: opts.version })}
+
     location = /healthz {
 ${proxyBlock}
     }
@@ -574,7 +742,7 @@ export interface IngressState {
    */
   gatewayPort?: number;
   /**
-   * Fingerprint of the SPA config injected into the served index. Undefined
+   * Fingerprint of the injected SPA config and its source bundle. Undefined
    * for webhooks-only edges and for SPA records that predate the field; an
    * SPA edge without a recorded fingerprint is treated as drifted and
    * restarted so the served index provably carries the requested config.
@@ -688,6 +856,8 @@ export function startIngressNginx(opts: {
       ? {
           remoteWebConfigHash: remoteWebConfigFingerprint(
             remoteWebIngress.config,
+            remoteWebIngress.webDistDir,
+            remoteWebIngress.version,
           ),
         }
       : {}),
@@ -857,7 +1027,7 @@ export async function startRemoteWebIngress(opts: {
     listenPort: number;
   }) => void;
 }): Promise<StartRemoteWebIngressResult> {
-  const listenPort = opts.listenPort ?? getNginxIngressPort();
+  let listenPort = opts.listenPort ?? getNginxIngressPort();
   const includeWebApp = opts.includeWebApp ?? true;
 
   const version = getNginxVersion();
@@ -868,18 +1038,45 @@ export async function startRemoteWebIngress(opts: {
   const running = isIngressRunning(opts.workspaceDir);
   const recorded = running ? readIngressState(opts.workspaceDir) : null;
   const recordedMode = recorded?.includeWebApp ?? true;
+  if (
+    recorded &&
+    opts.listenPort === undefined &&
+    process.env.CADET_NGINX_INGRESS_PORT === undefined
+  ) {
+    listenPort = recorded.listenPort;
+  }
   // The SPA config the served index must carry, computed up front so the
   // reuse decision and the actual spawn share one value and cannot drift.
   const spaOptions = includeWebApp
     ? {
-        hubUrl: cloudWebHubUrl(getCurrentEnvironment().name),
+        hubUrl: cloudAssistantHubUrl(getCurrentEnvironment().name),
         ...(opts.assistantName ? { assistantName: opts.assistantName } : {}),
         ...(opts.assistantId ? { assistantId: opts.assistantId } : {}),
       }
     : undefined;
-  const requestedConfigHash = spaOptions
-    ? remoteWebConfigFingerprint(remoteWebIngressConfig(spaOptions))
+  const webDistDir = includeWebApp ? findWebDistDir() : null;
+  if (includeWebApp && !webDistDir) {
+    return { status: "web-dist-missing" };
+  }
+  const runtimeVersion = webDistDir
+    ? await fetchCurrentVersion(`http://127.0.0.1:${opts.gatewayPort}`)
+    : undefined;
+  const webVersion = webDistDir ? readWebReleaseVersion(webDistDir) : undefined;
+  const assistantVersion = runtimeVersion
+    ? stripVersionPrefix(runtimeVersion)
     : undefined;
+  const matchedVersion =
+    assistantVersion && webVersion === assistantVersion
+      ? assistantVersion
+      : undefined;
+  const requestedConfigHash =
+    spaOptions && webDistDir
+      ? remoteWebConfigFingerprint(
+          remoteWebIngressConfig(spaOptions),
+          webDistDir,
+          matchedVersion,
+        )
+      : undefined;
   // Both sides are undefined in webhooks-only mode; an SPA record without a
   // fingerprint predates the field and counts as drifted (see IngressState).
   const configMatches = recorded?.remoteWebConfigHash === requestedConfigHash;
@@ -906,14 +1103,6 @@ export async function startRemoteWebIngress(opts: {
     return alreadyRunning();
   }
 
-  let webDistDir: string | null = null;
-  if (includeWebApp) {
-    webDistDir = findWebDistDir();
-    if (!webDistDir) {
-      return { status: "web-dist-missing" };
-    }
-  }
-
   // The running edge serves the other mode, targets a different gateway
   // port, or injects a stale SPA config; restart it with the requested
   // config. A false stop can mean the old edge exited on its own after the
@@ -926,13 +1115,32 @@ export async function startRemoteWebIngress(opts: {
     return alreadyRunning();
   }
 
+  // A foreign process squatting the default edge port (another assistant's
+  // edge, a stale dev server) must not kill the tunnel: the edge port is
+  // loopback-local and the public tunnel URL never carries it, so moving to
+  // the next free port is invisible to remote clients. Explicit pins
+  // (opts.listenPort / CADET_NGINX_INGRESS_PORT) keep their intent and still
+  // fail on a collision.
+  if (
+    opts.listenPort === undefined &&
+    process.env.CADET_NGINX_INGRESS_PORT === undefined
+  ) {
+    const discovered = await findAvailableIngressPort(listenPort);
+    if (discovered !== null && discovered !== listenPort) {
+      console.log(`Port ${listenPort} in use; using ${discovered} instead.`);
+      listenPort = discovered;
+    }
+  }
+
   opts.onStarting?.({ version, webDistDir, listenPort });
 
   const child = startIngressNginx({
     workspaceDir: opts.workspaceDir,
     gatewayPort: opts.gatewayPort,
     listenPort,
-    remoteWebIngress: webDistDir ? { webDistDir, ...spaOptions } : undefined,
+    remoteWebIngress: webDistDir
+      ? { webDistDir, ...spaOptions, version: matchedVersion }
+      : undefined,
   });
   let exited = false;
   child.once("exit", () => {
@@ -1042,6 +1250,7 @@ export async function stopContainerTunnelEdge(
 function stampAppProcessEntry(
   workspaceDir: string,
   assistantId?: string,
+  port = getNginxIngressPort(),
 ): void {
   const pid = getIngressPid(workspaceDir);
   if (pid !== null) {
@@ -1049,6 +1258,7 @@ function stampAppProcessEntry(
       pid,
       startedAt: new Date().toISOString(),
       assistantId,
+      port,
     });
   }
 }
@@ -1116,7 +1326,11 @@ export async function ensureTunnelEdge(opts: {
 
   switch (result.status) {
     case "started":
-      stampAppProcessEntry(opts.workspaceDir, opts.assistantId);
+      stampAppProcessEntry(
+        opts.workspaceDir,
+        opts.assistantId,
+        result.listenPort,
+      );
       return {
         port: result.listenPort,
         started: true,
@@ -1150,7 +1364,11 @@ export async function ensureTunnelEdge(opts: {
             stuckEdgeRecoveryHint(opts.workspaceDir),
         );
       }
-      stampAppProcessEntry(opts.workspaceDir, opts.assistantId);
+      stampAppProcessEntry(
+        opts.workspaceDir,
+        opts.assistantId,
+        result.listenPort,
+      );
       return {
         port: result.listenPort,
         started: false,

package/src/lib/process.ts

@@ -1,3 +1,4 @@
+import { DAEMON_STOP_TIMEOUT_MS } from "@mycadet/local-mode";
 import { execFileSync } from "child_process";
 import { existsSync, readFileSync, unlinkSync } from "fs";
 import { platform } from "os";
@@ -324,6 +325,7 @@ export async function stopProcess(
     });
   },
   readIdentity: (pid: number) => string | null = readPosixCommandLine,
+  gracefulOnly = false,
 ): Promise<boolean> {
   try {
     process.kill(pid, 0);
@@ -339,6 +341,9 @@ export async function stopProcess(
   console.log(`Stopping ${label} (pid ${pid})...`);
   let waitForGracefulExit = true;
   if (hostPlatform === "win32") {
+    if (gracefulOnly) {
+      throw new Error("Graceful-only shutdown is not supported for Windows local services.");
+    }
     try {
       runTaskkill(["/PID", String(pid), "/T"], timeoutMs);
     } catch {
@@ -363,6 +368,7 @@ export async function stopProcess(
   } catch {
     return true;
   }
+  if (gracefulOnly) return false;
   if (hostPlatform === "win32") {
     console.log(`${label} did not exit, terminating its process tree...`);
     try {
@@ -415,6 +421,13 @@ export async function stopProcess(
   }
 }
 
+/** Stop a service without escalation. Failure preserves PID tracking and aborts capture/replacement. */
+export async function stopProcessGracefully(pid: number, label: string, timeoutMs = DAEMON_STOP_TIMEOUT_MS): Promise<boolean> {
+  const stopped = await stopProcess(pid, label, timeoutMs, undefined, undefined, undefined, true);
+  if (!stopped) throw new Error(`${label} did not stop gracefully.`);
+  return stopped;
+}
+
 /** Remove one or more files, ignoring missing-file errors. */
 function removeFiles(...files: (string | string[] | undefined)[]): void {
   for (const entry of files) {