@monster-orange/den 0.2.5 → 0.2.7

package/src/ui/cli/service-command.ts

@@ -9,6 +9,11 @@
  * `install` (which also restarts a running service) says the service is
  * running only once the web server answers /api/server-info with JSON: a
  * fresh server takes a few seconds to start, and answers empty until then.
+ *
+ * `install --plan` is read-only: it prints the plist install would write
+ * (install.sh print), the label, the paths and whose server answers on the
+ * port, and writes and loads nothing; exit 1 when that server is foreign.
+ * `status` also names a foreign server on the port.
  */
 import { spawnSync } from "child_process";
 import * as os from "os";
@@ -20,6 +25,17 @@ import {
 } from "../../shared/den-config.js";
 import { readWebPort } from "../../shared/edge/config.js";
 import { getDistRoot, getEngineRoot } from "../../shared/paths.js";
+import { product } from "../../shared/product.js";
+import {
+  classifyServerInfo,
+  ForeignServerError,
+  foreignServerMessage,
+  identifyServer,
+  ownServer,
+  pickAnotherPortHint,
+  type OwnServer,
+  type ServerIdentity,
+} from "./server-identity.js";
 
 /** Runs a command with extra env vars; returns its exit code. */
 export type ServiceRunner = (
@@ -30,6 +46,14 @@ export type ServiceRunner = (
 
 const SUBCOMMANDS = ["install", "status", "print", "uninstall"] as const;
 
+/** The flags each subcommand takes; any other is refused before acting. */
+const SUBCOMMAND_FLAGS: Record<(typeof SUBCOMMANDS)[number], string[]> = {
+  install: ["--plan"],
+  status: [],
+  print: [],
+  uninstall: [],
+};
+
 const defaultRunner: ServiceRunner = (cmd, args, env) =>
   spawnSync(cmd, args, { stdio: "inherit", env: { ...process.env, ...env } })
     .status ?? 1;
@@ -39,12 +63,15 @@ export const READY_TIMEOUT_MS = 30_000;
 
 /**
  * Poll `url` until it answers 2xx with a JSON object, or `timeoutMs` passes.
- * Each attempt is bounded too, so a hung connection cannot outlast it.
+ * Each attempt is bounded too, so a hung connection cannot outlast it. A
+ * server that is not `own`'s (another distribution's, on the same port) is
+ * never "running": that throws ForeignServerError at once.
  */
 export async function waitForServerInfo(
   url: string,
   timeoutMs: number = READY_TIMEOUT_MS,
   intervalMs = 500,
+  own: OwnServer = ownServer(),
 ): Promise<boolean> {
   const deadline = Date.now() + timeoutMs;
   for (;;) {
@@ -56,9 +83,15 @@ export async function waitForServerInfo(
       });
       if (res.ok) {
         const body: unknown = JSON.parse(await res.text());
-        if (body !== null && typeof body === "object") return true;
+        if (body !== null && typeof body === "object") {
+          const id = classifyServerInfo(body, own);
+          if (id.kind === "foreign")
+            throw new ForeignServerError(Number(new URL(url).port), id.who);
+          return true;
+        }
       }
-    } catch {
+    } catch (e) {
+      if (e instanceof ForeignServerError) throw e;
       /* not up yet: refused, empty or partial body */
     }
     await new Promise((r) => setTimeout(r, intervalMs));
@@ -74,9 +107,32 @@ export interface ServiceDeps {
   platform?: NodeJS.Platform;
   /** The web UI port (default: config web.port). */
   webPort?: number;
-  /** Readiness poller (default: waitForServerInfo). */
-  waitReady?: (url: string, timeoutMs: number) => Promise<boolean>;
+  /**
+   * Readiness poller (default: waitForServerInfo). Throws
+   * ForeignServerError when another distribution's server answers.
+   */
+  waitReady?: (
+    url: string,
+    timeoutMs: number,
+    own: OwnServer,
+  ) => Promise<boolean>;
   log?: (line: string) => void;
+  /** Whose server answers on a port (default: identifyServer). */
+  identify?: (port: number, own: OwnServer) => Promise<ServerIdentity>;
+}
+
+/** One line on whose server answers on `port`. */
+export function identityLine(port: number, id: ServerIdentity): string {
+  switch (id.kind) {
+    case "none":
+      return `port ${port}: free (nothing listening)`;
+    case "unresponsive":
+      return `port ${port}: something accepted the connection but did not answer`;
+    case "ours":
+      return `port ${port}: this distribution's server${id.version ? ` (Den ${id.version})` : ""}${id.pid ? `, pid ${id.pid}` : ""}`;
+    case "foreign":
+      return `${foreignServerMessage(port, id.who)}; not this distribution's server`;
+  }
 }
 
 /** Run `service <sub>`; returns the exit code. */
@@ -84,13 +140,30 @@ export async function cmdService(
   args: string[],
   deps: ServiceDeps = {},
 ): Promise<number> {
-  const sub = args[0];
+  const sub = args[0] as (typeof SUBCOMMANDS)[number] | undefined;
   if (!(SUBCOMMANDS as readonly string[]).includes(sub ?? ""))
     throw new Error(
       `${sub ? `Unknown service command "${sub}". ` : ""}Use: ${SUBCOMMANDS.join(" | ")}`,
     );
-  // print only writes the plist; the rest talk to launchd.
-  if (sub !== "print" && (deps.platform ?? process.platform) !== "darwin")
+  // A typo'd --plan must not install for real.
+  const extra = args
+    .slice(1)
+    .filter((a) => !SUBCOMMAND_FLAGS[sub!].includes(a));
+  if (extra.length)
+    throw new Error(
+      `service ${sub}: unknown argument${extra.length > 1 ? "s" : ""} ${extra.join(" ")}` +
+        (SUBCOMMAND_FLAGS[sub!].length
+          ? ` (takes ${SUBCOMMAND_FLAGS[sub!].join(", ")})`
+          : ""),
+    );
+  const plan = sub === "install" && args.includes("--plan");
+  // print (and install --plan) only write the plist to stdout; the rest
+  // talk to launchd.
+  if (
+    sub !== "print" &&
+    !plan &&
+    (deps.platform ?? process.platform) !== "darwin"
+  )
     throw new Error(
       "the web UI service is a launchd LaunchAgent: macOS only (print works anywhere)",
     );
@@ -105,19 +178,70 @@ export async function cmdService(
     "service",
     "install.sh",
   );
-  const code = (deps.run ?? defaultRunner)("bash", [script, sub!], {
+  const env = {
     DEN_ROOT: distRoot,
     DEN_SERVICE_LABEL: label,
     DEN_SERVICE_LOGS: logs,
+  };
+  const run = deps.run ?? defaultRunner;
+  const log = deps.log ?? ((l: string) => console.log(l));
+  const port = deps.webPort ?? readWebPort(distRoot);
+  const own: OwnServer = { root: distRoot, product: product().name };
+  const identify =
+    deps.identify ?? ((p: number, o: OwnServer) => identifyServer(p, o));
+
+  if (plan) {
+    const home = deps.home ?? os.homedir();
+    log(`service install --plan (read-only: nothing is written or loaded)`);
+    log(`  label:   ${label}`);
+    log(
+      `  plist:   ${path.join(home, "Library", "LaunchAgents", `${label}.plist`)}`,
+    );
+    log(`  logs:    ${path.join(logs, "web.log")}`);
+    log(`  root:    ${distRoot}`);
+    log(`  engine:  ${path.dirname(path.dirname(script))}`);
+    log(`  url:     http://localhost:${port}`);
+    const id = await identify(port, own);
+    log(`  server:  ${identityLine(port, id)}`);
+    log(`  plist it would write:`);
+    // install.sh print writes the plist to stdout only.
+    const code = run("bash", [script, "print"], env);
+    if (code !== 0) return code;
+    if (id.kind === "foreign") {
+      log(`✗ install would refuse this port: ${pickAnotherPortHint()}`);
+      return 1;
+    }
+    return 0;
+  }
+
+  const code = run("bash", [script, sub!], {
+    ...env,
     // The script then leaves saying "running" to us (after the poll below).
     ...(sub === "install" ? { DEN_SERVICE_READY_CHECK: "external" } : {}),
   });
+  if (sub === "status") {
+    const id = await identify(port, own);
+    if (id.kind === "foreign") log(`✗ ${identityLine(port, id)}`);
+    return code;
+  }
   if (sub !== "install" || code !== 0) return code;
 
-  const log = deps.log ?? ((l: string) => console.log(l));
-  const port = deps.webPort ?? readWebPort(distRoot);
   const url = `http://localhost:${port}/api/server-info`;
-  if (await (deps.waitReady ?? waitForServerInfo)(url, READY_TIMEOUT_MS)) {
+  const waitReady =
+    deps.waitReady ??
+    ((u: string, t: number, o: OwnServer) => waitForServerInfo(u, t, 500, o));
+  let ready: boolean;
+  try {
+    ready = await waitReady(url, READY_TIMEOUT_MS, own);
+  } catch (e) {
+    if (!(e instanceof ForeignServerError)) throw e;
+    log(
+      `✗ ${label} installed, but ${foreignServerMessage(e.port, e.who)}, ` +
+        `so it cannot serve there: ${pickAnotherPortHint()}`,
+    );
+    return 1;
+  }
+  if (ready) {
     log(
       `✓ ${label} running at http://localhost:${port} (logs: ${path.join(logs, "web.log")})`,
     );

package/src/ui/cli/spinner.ts

@@ -0,0 +1,48 @@
+/**
+ * The CLI's progress spinners (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.
+ *
+ * They animate only on a terminal with a known, non-zero width. ora
+ * divides each line's width by the column count to know how many lines to
+ * clear before the next frame: on a pty that reports 0 columns (one nobody
+ * sized, as agent shells and some CI runners give) that is Infinity and the
+ * spinner clears lines forever. Without a usable terminal a spinner prints
+ * plain lines instead: its text once on start, and the final line.
+ */
+import oraSpinner, { type Ora } from "ora";
+
+/** A stream as a spinner sees it: a TTY, maybe, with a width, maybe. */
+export interface SpinnerStream extends NodeJS.WritableStream {
+  isTTY?: boolean;
+  columns?: number;
+}
+
+/** Whether a spinner can draw frames on `stream`. */
+export function canAnimate(stream: SpinnerStream): boolean {
+  return (
+    stream.isTTY === true &&
+    typeof stream.columns === "number" &&
+    Number.isFinite(stream.columns) &&
+    stream.columns > 0
+  );
+}
+
+function defaultStream(): SpinnerStream {
+  return process.stderr.isTTY ? process.stderr : process.stdout;
+}
+
+/** A spinner showing `text`, on stderr (a terminal) or stdout (piped). */
+export function spinner(
+  text: string,
+  stream: SpinnerStream = defaultStream(),
+): Ora {
+  return oraSpinner({
+    text,
+    stream: stream as NodeJS.WritableStream,
+    // Unset, ora decides (never under CI or TERM=dumb); false: plain lines.
+    ...(canAnimate(stream) ? {} : { isEnabled: false }),
+  });
+}

package/src/ui/cli/table.ts

@@ -0,0 +1,20 @@
+/**
+ * cli-table3 colours its borders (grey) and head cells (its own default, or
+ * the `style` given) through @colors/colors, which ignores Den's colour
+ * detection: piped `status` output carried ANSI codes from the table alone.
+ * Every CLI table goes through here, and takes no colour when chalk has none
+ * (not a TTY, NO_COLOR, FORCE_COLOR=0).
+ */
+import chalk from "chalk";
+import Table from "cli-table3";
+
+export function newTable(
+  opts: Table.TableConstructorOptions = {},
+  colour: boolean = chalk.level > 0,
+): Table.Table {
+  if (colour) return new Table(opts);
+  return new Table({
+    ...opts,
+    style: { ...(opts.style ?? {}), head: [], border: [] },
+  });
+}

package/src/ui/cli/validate-all.ts

@@ -0,0 +1,171 @@
+/**
+ * Bare `<cli> validate` in the distribution root: every manifest the
+ * distribution uses, without cloning anything.
+ *
+ * - Each repo of every workspace, once per distinct checkout path: its
+ *   layered manifest (own or held, then the override, then the merge).
+ * - A repo with no checkout on disk (a managed clone not made yet, a
+ *   dev-managed path that is gone) falls back to its held manifest, marked
+ *   "held only, no checkout"; with no held manifest either it is a warning,
+ *   not a failure.
+ * - Each held manifest (and override) in manifests/ that no repo above used.
+ *
+ * The layered validator comes in as `validate` (validateManifestLayers), so
+ * this file stays under the typecheck gate (see validate-layers.ts).
+ *
+ * `--held` checks only manifests/, as if nothing were checked out: a result
+ * that does not depend on the machine (an upgrade gate).
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { product } from "../../shared/product.js";
+import { readCatalog } from "../../shared/environment-manager/catalog.js";
+import {
+  readWorkspacesFile,
+  resolveServiceSource,
+} from "../../shared/environment-manager/workspaces.js";
+import {
+  heldManifestsDir,
+  overrideSuffix,
+} from "../../shared/manifest/read-manifest.js";
+import type { LayeredValidation } from "../../shared/manifest/validate-layers.js";
+
+export interface RepoValidation {
+  repo: string;
+  /** The checkout validated, or null when only manifests/ was read. */
+  checkout: string | null;
+  /** Workspaces that use this checkout. */
+  workspaces: string[];
+  /** own | held, plus "+ override" when one layered on. */
+  source: string;
+  /** Set when there was no checkout and the held manifest stood in. */
+  note?: string;
+  /** No checkout and no held manifest: reported, not failed. */
+  missing?: boolean;
+  result: LayeredValidation;
+}
+
+/**
+ * A path that never exists, named after the repo, so the layer lookup finds
+ * only manifests/<repo>… and never a checkout's own manifest.
+ */
+function heldOnlyPath(repo: string): string {
+  return path.join(heldManifestsDir(), ".held-only", repo);
+}
+
+function sourceOf(result: LayeredValidation): string {
+  const base = result.layers.find(
+    (l) => l.layer === "repo" || l.layer === "held",
+  );
+  const own = base?.layer === "repo" ? "own" : base ? "held" : "none";
+  return result.layers.some((l) => l.layer === "override")
+    ? `${own} + override`
+    : own;
+}
+
+/** The repo keys manifests/ holds a manifest or an override for. */
+function heldKeys(): string[] {
+  const dir = heldManifestsDir();
+  if (!fs.existsSync(dir)) return [];
+  const yml = product().manifestYml;
+  const over = overrideSuffix();
+  const keys = new Set<string>();
+  for (const name of fs.readdirSync(dir)) {
+    if (name.endsWith(over)) keys.add(name.slice(0, -over.length));
+    else if (name.endsWith(yml)) keys.add(name.slice(0, -yml.length));
+  }
+  return [...keys].sort();
+}
+
+type Validate = (repoPath: string) => LayeredValidation;
+
+function heldOnly(repo: string, validate: Validate): RepoValidation {
+  const result = validate(heldOnlyPath(repo));
+  return {
+    repo,
+    checkout: null,
+    workspaces: [],
+    source: sourceOf(result),
+    result,
+  };
+}
+
+export function validateAll(opts: {
+  held?: boolean;
+  validate: Validate;
+}): RepoValidation[] {
+  const { validate } = opts;
+  if (opts.held)
+    return heldKeys().map((k) => {
+      const r = heldOnly(k, validate);
+      // An override with no held base layers onto the repo's own manifest,
+      // which --held deliberately does not read: noted, not failed.
+      const overrideOnly =
+        r.result.layers.length > 0 &&
+        r.result.layers.every((l) => l.layer === "override");
+      return overrideOnly
+        ? {
+            ...r,
+            source: "override",
+            missing: true,
+            note: "override only: its base is the repo's own manifest (not read with --held)",
+          }
+        : r;
+    });
+
+  const file = readWorkspacesFile();
+  const catalog = readCatalog();
+  // repo + checkout path → the workspaces that use it.
+  const seen = new Map<
+    string,
+    { repo: string; path: string; workspaces: string[] }
+  >();
+  for (const [ws, config] of Object.entries(file.workspaces)) {
+    for (const address of Object.keys(config.services ?? {})) {
+      const src = resolveServiceSource(address, ws, config, catalog);
+      const repo = src?.repoName ?? address.split("/")[0];
+      const p = src?.repoPath ? path.resolve(src.repoPath) : "";
+      const key = `${repo}\0${p}`;
+      const hit = seen.get(key);
+      if (hit) {
+        if (!hit.workspaces.includes(ws)) hit.workspaces.push(ws);
+      } else seen.set(key, { repo, path: p, workspaces: [ws] });
+    }
+  }
+
+  const out: RepoValidation[] = [];
+  const used = new Set<string>();
+  for (const { repo, path: p, workspaces } of seen.values()) {
+    used.add(repo);
+    if (p && fs.existsSync(p)) {
+      const result = validate(p);
+      out.push({
+        repo,
+        checkout: p,
+        workspaces,
+        source: sourceOf(result),
+        result,
+        ...(result.layers.length === 0 ? { missing: true } : {}),
+      });
+      continue;
+    }
+    const held = heldOnly(repo, validate);
+    out.push({
+      ...held,
+      checkout: p || null,
+      workspaces,
+      ...(held.result.layers.length
+        ? { note: "held only, no checkout" }
+        : { missing: true, note: "no checkout and no held manifest" }),
+    });
+  }
+  for (const key of heldKeys())
+    if (!used.has(key))
+      out.push({ ...heldOnly(key, validate), note: "held, in no workspace" });
+  return out;
+}
+
+/** Whether the run fails: any layer invalid, ignoring `missing` entries. */
+export function validateAllFailed(results: RepoValidation[]): boolean {
+  return results.some((r) => !r.missing && !r.result.valid);
+}

package/src/ui/cli/web-command.ts

@@ -13,6 +13,12 @@ import { getDistRoot, getEngineRoot, getStateDir } from "../../shared/paths.js";
 import { hasDenUiMarker } from "../../shared/ui-marker.js";
 import { engineBin, engineModuleFile } from "../../shared/engine.js";
 import { readWebPort } from "../../shared/edge/config.js";
+import {
+  ownServer,
+  processCwd,
+  refuseForeignServer,
+  samePath,
+} from "./server-identity.js";
 
 import { product } from "../../shared/product.js";
 interface WebCommandOptions {
@@ -569,21 +575,55 @@ async function waitForPidsExit(pids: number[]): Promise<boolean> {
   return false;
 }
 
-function findDenWebPids(port: number): number[] {
+/**
+ * Whether `pid` may be this distribution's server by where it runs: a web
+ * server runs from its distribution root, so one whose working directory
+ * is another root is never ours, even when its command line matches (two
+ * distributions on one linked engine run the same entry point). An
+ * unreadable directory does not decide.
+ */
+function runsFromRoot(pid: number, root: string): boolean {
+  const cwd = processCwd(pid);
+  if (!cwd) return true;
+  return samePath(cwd, root);
+}
+
+function isOurWebPid(pid: number, root: string): boolean {
+  const command = commandForPid(pid);
+  return (
+    !!command &&
+    isDenWebCommand(command, webRoots(root)) &&
+    runsFromRoot(pid, root)
+  );
+}
+
+/**
+ * Our server's pids on `port`. `vouched` is the pid of a server the
+ * identity check (server-info: our root, or an older server run from our
+ * root) found ours: it is stopped when it listens on the port even if its
+ * command line names no entry point we recognise. Before, an older Den
+ * installed elsewhere, or a hand-started server, matched no command line,
+ * so `web down` said "not running" and `web restart` "already running".
+ */
+function findDenWebPids(port: number, vouched?: number): number[] {
   const root = getDistRoot();
   const pids = new Set<number>();
   const state = readWebServerState();
-  if (state?.port === port && state.pid) {
-    const command = commandForPid(state.pid);
-    if (command && isDenWebCommand(command, webRoots(state.root || root))) {
-      pids.add(state.pid);
-    }
+  const listeners = listListeningPids(port);
+  // The state file may be shared by distributions of one product name: a
+  // record of another root's server is not ours to stop.
+  if (
+    state?.port === port &&
+    state.pid &&
+    samePath(state.root || root, root) &&
+    (isOurWebPid(state.pid, root) ||
+      (state.pid === vouched && listeners.includes(state.pid)))
+  ) {
+    pids.add(state.pid);
   }
 
-  for (const pid of listListeningPids(port)) {
-    if (isDenWebCommand(commandForPid(pid), webRoots(root))) {
-      pids.add(pid);
-    }
+  for (const pid of listeners) {
+    if (pid === vouched || isOurWebPid(pid, root)) pids.add(pid);
   }
 
   return Array.from(pids);
@@ -611,8 +651,11 @@ export function killWebProcess(pid: number, signal: NodeJS.Signals): void {
   }
 }
 
-async function stopDenWebServer(port: number): Promise<StopServerResult> {
-  const pids = findDenWebPids(port);
+async function stopDenWebServer(
+  port: number,
+  vouched?: number,
+): Promise<StopServerResult> {
+  const pids = findDenWebPids(port, vouched);
   if (pids.length === 0) {
     const state = readWebServerState();
     if (state?.port === port) removeWebServerState();
@@ -636,22 +679,25 @@ async function stopDenWebServer(port: number): Promise<StopServerResult> {
   return { stopped: forced, forced: true, pids };
 }
 
-async function stopBrokenDenWebServer(port: number): Promise<boolean> {
-  return (await stopDenWebServer(port)).stopped;
+async function stopBrokenDenWebServer(
+  port: number,
+  vouched?: number,
+): Promise<boolean> {
+  return (await stopDenWebServer(port, vouched)).stopped;
 }
 
 function recordRunningDenWebServer(port: number): void {
   const root = getDistRoot();
   const state = readWebServerState();
-  if (state?.port === port && state.pid) {
-    const command = commandForPid(state.pid);
-    if (command && isDenWebCommand(command, webRoots(state.root || root)))
-      return;
-  }
+  if (
+    state?.port === port &&
+    state.pid &&
+    samePath(state.root || root, root) &&
+    isOurWebPid(state.pid, root)
+  )
+    return;
 
-  const pids = listListeningPids(port).filter((pid) =>
-    isDenWebCommand(commandForPid(pid), webRoots(root)),
-  );
+  const pids = listListeningPids(port).filter((pid) => isOurWebPid(pid, root));
   const pid = pids[0];
   if (!pid) return;
 
@@ -965,8 +1011,13 @@ export async function cmdWeb(args: string[]): Promise<void> {
 
   const url = buildDenWebUrl(options.port);
 
+  // Never act on another distribution's server: not "already running", and
+  // never a signal to it (down, restart).
+  const identity = await refuseForeignServer(options.port, ownServer());
+  const vouched = identity.kind === "ours" ? identity.pid : undefined;
+
   if (options.action === "down") {
-    const stopped = await stopDenWebServer(options.port);
+    const stopped = await stopDenWebServer(options.port, vouched);
     if (stopped.stopped) {
       const mode = stopped.forced ? "force stopped" : "stopped";
       console.log(
@@ -988,7 +1039,7 @@ export async function cmdWeb(args: string[]): Promise<void> {
   }
 
   if (options.action === "restart") {
-    const stopped = await stopDenWebServer(options.port);
+    const stopped = await stopDenWebServer(options.port, vouched);
     if (stopped.pids.length > 0 && !stopped.stopped) {
       throw new Error(
         `Could not stop ${product().title} web on port ${options.port}.`,
@@ -1015,7 +1066,7 @@ export async function cmdWeb(args: string[]): Promise<void> {
       ),
     );
     console.log(chalk.gray(`  Restarting ${product().title} web...`));
-    const stopped = await stopBrokenDenWebServer(options.port);
+    const stopped = await stopBrokenDenWebServer(options.port, vouched);
     if (!stopped) {
       throw new Error(
         `Could not stop the broken ${product().title} web server on port ${options.port}.`,