@monster-orange/den 0.2.5 → 0.2.6

package/src/shared/stacks/compose-health.ts

@@ -58,13 +58,19 @@ export function composeHealthTarget(
 /** Budget for the shared listing; past it the checks are pending. */
 export const COMPOSE_LISTING_TIMEOUT_MS = 5_000;
 
-type Listing = { rows: ComposeRow[] } | { error: string; pending?: boolean };
+/** The shared listing: every container, or why docker could not answer. */
+export type ComposeListing =
+  | { rows: ComposeRow[] }
+  | { error: string; pending?: boolean };
+type Listing = ComposeListing;
 
 let inFlight: Promise<Listing> | null = null;
 
 /**
- * Every compose container, from one `docker ps -a`. Concurrent callers share
- * the call in flight, so a health cycle lists once however many checks it has.
+ * Every container, from one `docker ps -a`. Concurrent callers share the
+ * call in flight, so a health cycle lists once however many checks it has
+ * (compose checks and `type: container` checks alike). Not filtered to
+ * compose containers: a container check may name a plain container.
  */
 export function composeListing(): Promise<Listing> {
   return (inFlight ??= listOnce().finally(() => {
@@ -96,10 +102,8 @@ function listOnce(): Promise<Listing> {
       [
         "ps",
         "-a",
-        "--filter",
-        "label=com.docker.compose.project",
         "--format",
-        '{{.Label "com.docker.compose.project"}}\t{{.Label "com.docker.compose.service"}}\t{{.State}}\t{{.Status}}',
+        '{{.Label "com.docker.compose.project"}}\t{{.Label "com.docker.compose.service"}}\t{{.State}}\t{{.Status}}\t{{.Names}}',
       ],
       {
         encoding: "utf-8",
@@ -125,9 +129,14 @@ function listOnce(): Promise<Listing> {
           .split("\n")
           .filter(Boolean)
           .map((line) => {
-            const [project = "", service = "", state = "", status = ""] =
-              line.split("\t");
-            return { project, service, state, status };
+            const [
+              project = "",
+              service = "",
+              state = "",
+              status = "",
+              name = "",
+            ] = line.split("\t");
+            return { project, service, state, status, name };
           });
         resolve({ rows });
       },
@@ -135,16 +144,99 @@ function listOnce(): Promise<Listing> {
   });
 }
 
+/**
+ * The verdict when docker gave no listing, shared by compose and container
+ * checks so the two cannot drift: container state unknown is not "not
+ * running" (`ok: null`, never down, however often it repeats). Only a
+ * listing past its budget is `pending` (no answer in time), which, like any
+ * timeout, is down when it repeats on the next cycle.
+ */
+export function unknownListingVerdict(listing: {
+  error: string;
+  pending?: boolean;
+}): ComposeVerdict {
+  return {
+    ok: null,
+    detail: `container state unknown: ${listing.error}`,
+    ...(listing.pending ? { pending: true } : {}),
+  };
+}
+
 /** The health of one Den-generated compose check, from the shared listing. */
 export async function composeHealth(
   target: ComposeHealthTarget,
 ): Promise<ComposeVerdict> {
   const listing = await composeListing();
-  if ("error" in listing)
+  if ("error" in listing) return unknownListingVerdict(listing);
+  return judgeStackRows(listing.rows, target.project, target.service);
+}
+
+// ── `health: { type: container }` ───────────────────────────────────────────
+
+/**
+ * A declared container check: a compose container by its project and service
+ * labels, or any container by name (`container_name`).
+ */
+export type ContainerHealthTarget =
+  | { project: string; service: string; container_name?: undefined }
+  | { container_name: string; project?: undefined; service?: undefined };
+
+/** What a container check shows as its check: `container <project>/<service>`. */
+export function containerCheckLabel(t: ContainerHealthTarget): string {
+  return `container ${containerTargetName(t)}`;
+}
+
+function containerTargetName(t: ContainerHealthTarget): string {
+  return t.container_name ?? `${t.project}/${t.service}`;
+}
+
+function matchesTarget(r: ComposeRow, t: ContainerHealthTarget): boolean {
+  if (t.container_name)
+    return (r.name ?? "")
+      .split(",")
+      .map((n) => n.trim().replace(/^\//, ""))
+      .includes(t.container_name);
+  return r.project === t.project && r.service === t.service;
+}
+
+/** One container's verdict: its healthcheck when it has one, else running. */
+function rowVerdict(r: ComposeRow): ComposeVerdict & { rank: number } {
+  const what = `${r.name || `${r.project}/${r.service}`}\t${r.state}\t${r.status}`;
+  if (r.state !== "running") return { ok: false, detail: what, rank: 4 };
+  if (/\(unhealthy\)/.test(r.status))
+    return { ok: false, detail: what, rank: 3 };
+  // Starting is pending, but not "no answer": it never turns down on repeat.
+  if (/\(health: starting\)/.test(r.status))
+    return { ok: null, detail: what, rank: 2 };
+  if (/\(healthy\)/.test(r.status)) return { ok: true, detail: what, rank: 0 };
+  return { ok: true, detail: what, rank: 1 };
+}
+
+/**
+ * The verdict of a container check over the shared listing. More than one
+ * match: the best one (healthy, then running). No match: down. No listing:
+ * as a compose check (unknownListingVerdict), the reason in `detail`.
+ */
+export function judgeContainerListing(
+  listing: ComposeListing,
+  target: ContainerHealthTarget,
+): ComposeVerdict {
+  if ("error" in listing) return unknownListingVerdict(listing);
+  const best = listing.rows
+    .filter((r) => matchesTarget(r, target))
+    .map(rowVerdict)
+    .sort((a, b) => a.rank - b.rank)[0];
+  if (!best)
     return {
-      ok: null,
-      detail: `container state unknown: ${listing.error}`,
-      ...(listing.pending ? { pending: true } : {}),
+      ok: false,
+      detail: `${containerTargetName(target)}: no container`,
     };
-  return judgeStackRows(listing.rows, target.project, target.service);
+  return { ok: best.ok, detail: best.detail };
+}
+
+/** The health of a declared container check, from the shared listing. */
+export async function containerHealth(
+  target: ContainerHealthTarget,
+): Promise<ComposeVerdict> {
+  return judgeContainerListing(await composeListing(), target);
 }

package/src/shared/stacks/runtime.ts

@@ -413,6 +413,8 @@ export interface ComposeRow {
   service: string;
   state: string;
   status: string;
+  /** The container's name(s), comma-separated as docker lists them. */
+  name?: string;
 }
 
 /**

package/src/shared/types/index.ts

@@ -210,10 +210,22 @@ export type LogSource =
  *   type: shell
  *   cmd: "docker exec $(docker ps --filter ancestor=postgres:16 --format '{{.ID}}' | head -1) pg_isready -U postgres"
  *   label: "postgres"   # optional — shown in UI instead of cmd
+ *
+ * Container (answered from the one `docker ps` a health cycle shares):
+ *   type: container
+ *   project: shop-main     # com.docker.compose.project label
+ *   service: db            # com.docker.compose.service label
+ *   -- or, for a container not run by compose --
+ *   type: container
+ *   container_name: shop-db
  */
 export type ServiceHealthConfig =
   | { type?: "http"; url: string; label?: string }
-  | { type: "shell"; cmd: string; label?: string };
+  | { type: "shell"; cmd: string; label?: string }
+  | ({ type: "container"; label?: string } & (
+      | { project: string; service: string; container_name?: undefined }
+      | { container_name: string; project?: undefined; service?: undefined }
+    ));
 
 /**
  * A command can be a plain shell string (detached by default) or an object

package/src/ui/cli/create.ts

@@ -15,6 +15,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { ENGINE_PACKAGE, getEngineRoot } from "../../shared/paths.js";
 import { profileFrom } from "../../shared/profile.js";
+import { plural } from "../../shared/plural.js";
 
 export interface CreateOptions {
   /** Product name: lower-case `[a-z][a-z0-9-]*`. */
@@ -345,7 +346,7 @@ export function runCreate(argv: string[], cwd: string): number {
     const cli = args.cli ?? args.name;
     const rel = path.relative(cwd, args.dir) || ".";
     console.log(
-      `Created ${args.name} in ${args.dir} (${written.length} files).`,
+      `Created ${args.name} in ${args.dir} (${plural(written.length, "file")}).`,
     );
     console.log("");
     console.log("Next:");

package/src/ui/cli/index.ts

@@ -12,18 +12,10 @@ import {
 } from "../../shared/stacks/status.js";
 import { isNamedTarget } from "./named-target.js";
 import chalk from "chalk";
-import oraSpinner from "ora";
-
-/**
- * Spinners are progress, not diagnostics: on a terminal they animate on
- * stderr as usual; piped (CI, scripts) their lines go to stdout so stderr
- * carries only real warnings and errors.
- */
-const ora = (text: string) =>
-  oraSpinner({
-    text,
-    stream: process.stderr.isTTY ? process.stderr : process.stdout,
-  });
+import { noun, plural } from "../../shared/plural.js";
+// Spinners: progress on stderr (a terminal) or stdout (piped); plain lines
+// where they cannot animate. See spinner.ts.
+import { spinner as ora } from "./spinner.js";
 import Table from "cli-table3";
 import { cliPrompts } from "./prompts.js";
 import { resultsViewer } from "./results-viewer.js";
@@ -87,6 +79,7 @@ import {
 import {
   blueprintWorkspaces,
   defaultWorkspaceNeedsSeeding,
+  blueprintAlreadySeeded,
   defaultWorkspaceHasServices,
   isMultiBlueprint,
   seedBlueprintWorkspaces,
@@ -496,8 +489,6 @@ function printValidation(
   layer?: string,
 ): void {
   const tag = layer ? `${layer}, ` : "";
-  const plural = (n: number, word: string): string =>
-    `${n} ${word}${n === 1 ? "" : "s"}`;
   if (result.valid && result.warnings.length === 0) {
     console.log(
       chalk.green(`  ✓  ${label}`) +
@@ -2284,7 +2275,7 @@ class DenCLI {
     }
     console.log(
       chalk.cyan(
-        `\n  ${only ? "Application" : "Workspace-wide"} up — ${chalk.bold(String(order.length))} systems`,
+        `\n  ${only ? "Application" : "Workspace-wide"} up — ${chalk.bold(String(order.length))} ${noun(order.length, "system")}`,
       ),
     );
     console.log(chalk.gray(`  Order: ${order.join(" → ")}\n`));
@@ -2345,7 +2336,7 @@ class DenCLI {
     const order = [...target.rawOrder].reverse();
     console.log(
       chalk.cyan(
-        `\n  ${only ? "Application" : "Workspace-wide"} down — ${chalk.bold(String(order.length))} systems`,
+        `\n  ${only ? "Application" : "Workspace-wide"} down — ${chalk.bold(String(order.length))} ${noun(order.length, "system")}`,
       ),
     );
     console.log(chalk.gray(`  Order: ${order.join(" → ")}\n`));
@@ -2516,13 +2507,26 @@ class DenCLI {
       return false;
     }
     const multi = isMultiBlueprint();
+    // A repeat seed: say so, and touch nothing.
+    if (blueprintAlreadySeeded()) {
+      console.log(
+        chalk.green(
+          multi
+            ? `\n  ✓ ${plural(bps.length, "workspace")} already seeded (${bps.map((b) => b.name).join(", ")}): nothing changed.\n`
+            : `\n  ✓ Default workspace already seeded — ${plural(bps[0].repos.length, "repo")} (managed): nothing changed.\n`,
+        ),
+      );
+      return false;
+    }
     const willReset = defaultWorkspaceHasServices();
     const interactive = !!(process.stdin.isTTY && process.stdout.isTTY);
 
     for (const bp of bps) {
       const label = multi ? `Workspace ${bp.name}` : "Default workspace";
       console.log(
-        chalk.cyan(`\n  ${label} — ${bp.repos.length} repos, all managed:`),
+        chalk.cyan(
+          `\n  ${label} — ${plural(bp.repos.length, "repo")}, all managed:`,
+        ),
       );
       console.log(chalk.gray(`    ${bp.repos.join(", ")}`));
     }
@@ -2563,7 +2567,7 @@ class DenCLI {
       const focus = readWorkspacesFile().focus;
       console.log(
         chalk.green(
-          `  ✓ ${seeded.length} workspaces ready (${seeded.map((w) => w.name).join(", ")}), all active; focus: ${focus}. ` +
+          `  ✓ ${plural(seeded.length, "workspace")} ${willReset ? "reset to the blueprint" : "ready"} (${seeded.map((w) => w.name).join(", ")}), all active; focus: ${focus}. ` +
             `Run \`${product().cli} up <repo>\` to bring up its closure.\n`,
         ),
       );
@@ -2572,7 +2576,7 @@ class DenCLI {
     const seeded = seedDefaultWorkspace();
     console.log(
       chalk.green(
-        `  ✓ Default workspace ready — ${seeded.length} repos (managed). ` +
+        `  ✓ Default workspace ${willReset ? "reset to the blueprint" : "ready"} — ${plural(seeded.length, "repo")} (managed). ` +
           `Run \`${product().cli} up <repo>\` to bring up its closure.\n`,
       ),
     );
@@ -2602,7 +2606,7 @@ class DenCLI {
     if (added.length > 0) {
       console.log(
         chalk.gray(
-          `  default workspace: added standard repo(s) ${added.join(", ")} (managed)`,
+          `  default workspace: added standard ${noun(added.length, "repo")} ${added.join(", ")} (managed)`,
         ),
       );
     }
@@ -3802,7 +3806,7 @@ class DenCLI {
     if (missing.length > 0) {
       console.log(
         chalk.cyan(
-          `\n  Cloning ${missing.length} managed repo(s) not on disk yet: ${missing.join(", ")}`,
+          `\n  Cloning ${plural(missing.length, "managed repo")} not on disk yet: ${missing.join(", ")}`,
         ),
       );
       await this.ensureManagedClonesFor(missing);

package/src/ui/cli/mcp-connect.ts

@@ -25,6 +25,13 @@ import { product } from "../../shared/product.js";
 import { getDistRoot } from "../../shared/paths.js";
 import { readWebPort } from "../../shared/edge/config.js";
 import { DEFAULT_PORT } from "../../shared/constants.js";
+import {
+  classifyServerInfo,
+  foreignServerMessage,
+  ownServer,
+  pickAnotherPortHint,
+  type OwnServer,
+} from "./server-identity.js";
 import { readDenConfig, readMcpConfig } from "../../shared/den-config.js";
 
 export const MCP_CONNECT_SUBCOMMANDS = [
@@ -205,6 +212,8 @@ export const WEB_PROBE_TIMEOUT_MS = 1500;
 /** What a probe of the web server's /api/server-info found. */
 export type WebProbe =
   | { kind: "up"; version?: string }
+  /** Another distribution's server (see server-identity.ts). */
+  | { kind: "foreign"; who: string }
   /** Something accepted the connection but sent no answer in time. */
   | { kind: "timeout" }
   /** Nothing answered: connection refused, or not the web server. */
@@ -214,13 +223,15 @@ export async function probeWebServer(
   url: string,
   timeoutMs: number = WEB_PROBE_TIMEOUT_MS,
   fetchImpl: typeof fetch = fetch,
+  own: OwnServer = ownServer(),
 ): Promise<WebProbe> {
   try {
     const r = await fetchImpl(`${url}/api/server-info`, {
       signal: AbortSignal.timeout(timeoutMs),
     });
-    const info = (await r.json()) as { version?: string };
-    return { kind: "up", version: info.version };
+    const id = classifyServerInfo(await r.json(), own);
+    if (id.kind === "foreign") return { kind: "foreign", who: id.who };
+    return { kind: "up", version: id.kind === "ours" ? id.version : undefined };
   } catch (e) {
     return (e as Error).name === "TimeoutError"
       ? { kind: "timeout" }
@@ -252,6 +263,11 @@ export function webServerMessage(
       chalk.green(`web server up at ${url}`) +
       (probe.version ? chalk.gray(` (Den ${probe.version})`) : "")
     );
+  if (probe.kind === "foreign")
+    return chalk.yellow(
+      `${foreignServerMessage(Number(new URL(url).port), probe.who)}: ` +
+        `agents would read another distribution; ${pickAnotherPortHint(opts.cli)}`,
+    );
   const svc = `\`${opts.cli} service status\``;
   if (probe.kind === "timeout") {
     const secs = (opts.timeoutMs ?? WEB_PROBE_TIMEOUT_MS) / 1000;
@@ -271,7 +287,7 @@ export function webServerMessage(
   );
 }
 
-async function webServerLine(port?: number): Promise<string> {
+function webUrl(port?: number): string {
   let p = port;
   if (p === undefined) {
     try {
@@ -280,8 +296,12 @@ async function webServerLine(port?: number): Promise<string> {
       p = DEFAULT_PORT;
     }
   }
-  const url = `http://localhost:${p}`;
-  return webServerMessage(await probeWebServer(url), url, {
+  return `http://localhost:${p}`;
+}
+
+async function webServerLine(port?: number, probe?: WebProbe): Promise<string> {
+  const url = webUrl(port);
+  return webServerMessage(probe ?? (await probeWebServer(url)), url, {
     cli: product().cli,
     asService: webRunsAsService(),
   });
@@ -382,6 +402,17 @@ export async function runMcpConnect(argv: string[]): Promise<number> {
     return 1;
   }
 
+  // Never point agents at another distribution's server.
+  if (!remove) {
+    const probe = await probeWebServer(webUrl(flags.port));
+    if (probe.kind === "foreign") {
+      console.error(
+        `  ${chalk.red("✗")} ${await webServerLine(flags.port, probe)}`,
+      );
+      return 1;
+    }
+  }
+
   let failed = 0;
   for (const c of targets) {
     if (!c.scopes.includes(scope)) {

package/src/ui/cli/server-identity.ts

@@ -0,0 +1,233 @@
+/**
+ * Whether the web server answering on a port is THIS distribution's.
+ *
+ * Several distributions can run a Den web server on one machine (each with
+ * its own root), so something answering on the configured port is not
+ * proof it is ours: `<cli> web up` once printed "already running" for
+ * another distribution's server, and `web down` could have signalled it.
+ * /api/server-info names the distribution root it serves and the product
+ * (since 0.2.6); every command that acts on "our" server asks this module
+ * first and refuses to act on a foreign one.
+ *
+ * A server from before 0.2.6 has no `root`. It does report its pid, and it
+ * runs with its distribution root as its working directory (`web up` and
+ * the launchd service both start it there), so that decides instead.
+ */
+import { spawnSync } from "child_process";
+import * as fs from "fs";
+import * as http from "http";
+import * as path from "path";
+import { CLI_SPAWN_TIMEOUT_MS } from "../../shared/constants.js";
+import { getDistRoot } from "../../shared/paths.js";
+import { product } from "../../shared/product.js";
+
+/** The distribution a command acts for. */
+export interface OwnServer {
+  root: string;
+  product: string;
+}
+
+/** What answers on a port, from this distribution's point of view. */
+export type ServerIdentity =
+  /** Nothing listens there. */
+  | { kind: "none" }
+  /** Something accepted the connection but sent no answer in time. */
+  | { kind: "unresponsive" }
+  /**
+   * `pid`: the server's own pid (server-info reports it). Identity is what
+   * makes it ours, so a stop signals this pid even when its command line
+   * names no entry point we recognise (an older Den installed elsewhere, a
+   * hand-started server).
+   */
+  | { kind: "ours"; version?: string; pid?: number }
+  /** Someone else's server. `who` reads "acme-ops at /srv/acme-ops". */
+  | { kind: "foreign"; who: string };
+
+/** How long one probe of /api/server-info may take. */
+export const SERVER_INFO_TIMEOUT_MS = 1_500;
+
+/** This distribution: its root and product name. */
+export function ownServer(): OwnServer {
+  return { root: getDistRoot(), product: product().name };
+}
+
+function canonical(p: string): string {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return path.resolve(p);
+  }
+}
+
+export function samePath(a: string, b: string): boolean {
+  return canonical(a) === canonical(b);
+}
+
+/** A process's working directory (lsof), or null when it can't be read. */
+export function processCwd(pid: number): string | null {
+  const r = spawnSync("lsof", ["-a", "-p", String(pid), "-d", "cwd", "-Fn"], {
+    encoding: "utf-8",
+    timeout: CLI_SPAWN_TIMEOUT_MS,
+  });
+  if (r.status !== 0 || typeof r.stdout !== "string") return null;
+  const line = r.stdout.split(/\r?\n/).find((l) => l.startsWith("n"));
+  return line ? line.slice(1) : null;
+}
+
+/**
+ * Classify a parsed /api/server-info body. `cwdOf` reads a pid's working
+ * directory, for servers from before `root` was reported.
+ */
+export function classifyServerInfo(
+  body: unknown,
+  own: OwnServer,
+  cwdOf: (pid: number) => string | null = processCwd,
+): ServerIdentity {
+  if (body === null || typeof body !== "object" || Array.isArray(body))
+    return { kind: "foreign", who: "a non-Den server" };
+  const info = body as Record<string, unknown>;
+  const version = typeof info.version === "string" ? info.version : undefined;
+  const prod = typeof info.product === "string" ? info.product : undefined;
+  const pid =
+    typeof info.pid === "number" && Number.isInteger(info.pid) && info.pid > 0
+      ? info.pid
+      : undefined;
+  const ours = (): ServerIdentity => ({
+    kind: "ours",
+    ...(version !== undefined ? { version } : {}),
+    ...(pid !== undefined ? { pid } : {}),
+  });
+
+  if (typeof info.root === "string" && info.root) {
+    if (
+      samePath(info.root, own.root) &&
+      (prod === undefined || prod === own.product)
+    )
+      return ours();
+    return {
+      kind: "foreign",
+      who: `${prod ?? "another server"} at ${info.root}`,
+    };
+  }
+
+  if (pid !== undefined) {
+    const cwd = cwdOf(pid);
+    if (cwd && samePath(cwd, own.root)) return ours();
+  }
+  if (version === undefined && info.pid === undefined)
+    return { kind: "foreign", who: "a non-Den server" };
+  return {
+    kind: "foreign",
+    who: `another server${version ? ` (Den ${version})` : ""}`,
+  };
+}
+
+/** Classify a raw /api/server-info answer (status and body text). */
+export function classifyServerInfoResponse(
+  statusCode: number,
+  text: string,
+  own: OwnServer,
+  cwdOf?: (pid: number) => string | null,
+): ServerIdentity {
+  // A server still starting answers 200 with an empty body: not up yet.
+  if (statusCode >= 200 && statusCode < 300 && text.trim() === "")
+    return { kind: "unresponsive" };
+  if (statusCode < 200 || statusCode >= 300)
+    return { kind: "foreign", who: "a non-Den server" };
+  let body: unknown;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    return { kind: "foreign", who: "a non-Den server" };
+  }
+  return classifyServerInfo(body, own, cwdOf);
+}
+
+/**
+ * GET /api/server-info on `port` and say whose server answered. `host`: the
+ * name the caller itself connects to (the MCP server's `localhost`).
+ */
+export function identifyServer(
+  port: number,
+  own: OwnServer = ownServer(),
+  timeoutMs: number = SERVER_INFO_TIMEOUT_MS,
+  host: string = "127.0.0.1",
+): Promise<ServerIdentity> {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (v: ServerIdentity): void => {
+      if (settled) return;
+      settled = true;
+      resolve(v);
+    };
+    const req = http.get(
+      {
+        host,
+        port,
+        path: "/api/server-info",
+        timeout: timeoutMs,
+        agent: false,
+      },
+      (res) => {
+        let text = "";
+        res.setEncoding("utf-8");
+        res.on("data", (chunk: string) => {
+          text += chunk;
+          if (text.length > 1024 * 1024) {
+            req.destroy();
+            finish({ kind: "foreign", who: "a non-Den server" });
+          }
+        });
+        res.on("end", () =>
+          finish(classifyServerInfoResponse(res.statusCode ?? 0, text, own)),
+        );
+        res.on("error", () => finish({ kind: "unresponsive" }));
+      },
+    );
+    req.on("timeout", () => {
+      req.destroy();
+      finish({ kind: "unresponsive" });
+    });
+    req.on("error", (e: NodeJS.ErrnoException) =>
+      finish(
+        e.code === "ECONNREFUSED" ? { kind: "none" } : { kind: "unresponsive" },
+      ),
+    );
+  });
+}
+
+/** "port 7001 is in use by acme-ops at /srv/acme-ops". */
+export function foreignServerMessage(port: number, who: string): string {
+  return `port ${port} is in use by ${who}`;
+}
+
+/** How to get out of the way: another port, for once or for good. */
+export function pickAnotherPortHint(cli: string = product().cli): string {
+  return (
+    `pick another port: \`${cli} web up --port <n>\` for once, or set ` +
+    `web.port in config/local/user.yml (yours) or ${product().configFile} (the team's)`
+  );
+}
+
+/** The error a command raises instead of acting on a foreign server. */
+export class ForeignServerError extends Error {
+  constructor(
+    readonly port: number,
+    readonly who: string,
+  ) {
+    super(
+      `${foreignServerMessage(port, who)}\n  Hint: ${pickAnotherPortHint()}`,
+    );
+    this.name = "ForeignServerError";
+  }
+}
+
+/** Throw ForeignServerError when `port` is served by another distribution. */
+export async function refuseForeignServer(
+  port: number,
+  own: OwnServer = ownServer(),
+): Promise<ServerIdentity> {
+  const id = await identifyServer(port, own);
+  if (id.kind === "foreign") throw new ForeignServerError(port, id.who);
+  return id;
+}