@canonical/pragma-cli 0.31.0 → 0.33.0

package/src/capabilities/doctor/checks/checkMcpCommands.ts

@@ -0,0 +1,114 @@
+import { existsSync } from "node:fs";
+import { delimiter, isAbsolute, join } from "node:path";
+import type { DetectedHarness } from "@canonical/harnesses";
+import { detectHarnesses, readMcpConfig } from "@canonical/harnesses";
+import { runTask } from "@canonical/task/node";
+import type { CheckItem, CheckResult } from "../types.js";
+import { deriveBand } from "./deriveBand.js";
+
+const NAME = "MCP commands";
+
+/**
+ * Extract the stdio command from an MCP server config entry, if any. HTTP/SSE
+ * entries (`{ type: "http", url }`) have no command and are not checked.
+ */
+function commandOf(entry: unknown): string | undefined {
+  if (typeof entry !== "object" || entry === null) return undefined;
+  const command = (entry as { command?: unknown }).command;
+  return typeof command === "string" && command.length > 0
+    ? command
+    : undefined;
+}
+
+/**
+ * Resolve a command the way a shell would: a path-bearing entry is checked as a
+ * file (relative to the project root), a bare name is searched across `PATH`.
+ */
+function commandResolves(command: string, cwd: string): boolean {
+  if (command.includes("/") || command.includes("\\")) {
+    return existsSync(isAbsolute(command) ? command : join(cwd, command));
+  }
+  return (process.env.PATH ?? "")
+    .split(delimiter)
+    .filter((dir) => dir.length > 0)
+    .some((dir) => existsSync(join(dir, command)));
+}
+
+/**
+ * Check that every command-based MCP server entry in detected harness configs
+ * resolves to an executable. A dead entry makes every agent session try and
+ * fail to boot it, so it is flagged with its config path.
+ *
+ * @param cwd - The project root to detect harnesses against.
+ * @returns pass (all resolve), fail (listing broken entries), or skip (nothing
+ *   to check).
+ * @note Impure — detects harnesses, reads configs, and probes PATH/the fs.
+ */
+export async function checkMcpCommands(cwd: string): Promise<CheckResult> {
+  let detected: DetectedHarness[];
+  try {
+    detected = await runTask(detectHarnesses(cwd));
+  } catch {
+    return { name: NAME, status: "skip", detail: "harness detection failed" };
+  }
+
+  const withConfig = detected.filter((d) => d.configExists);
+  if (withConfig.length === 0) {
+    return { name: NAME, status: "skip", detail: "no MCP configs found" };
+  }
+
+  // Band the finding by the harnesses whose configs were actually examined, so
+  // a global-scope harness's broken command is reported under the global band.
+  const band = deriveBand(withConfig);
+  const broken: CheckItem[] = [];
+  let checked = 0;
+
+  for (const d of withConfig) {
+    let servers: Record<string, unknown>;
+    try {
+      servers = await runTask(readMcpConfig(d.harness, cwd));
+    } catch {
+      continue; // The "MCP configured" check reports on unreadable configs.
+    }
+
+    for (const [serverName, entry] of Object.entries(servers)) {
+      const command = commandOf(entry);
+      if (!command) continue;
+      checked += 1;
+      if (!commandResolves(command, cwd)) {
+        broken.push({
+          label: `"${serverName}"`,
+          status: "fail",
+          detail: `"${command}" not found · ${d.configPath}`,
+        });
+      }
+    }
+  }
+
+  if (checked === 0) {
+    return {
+      name: NAME,
+      status: "skip",
+      detail: "no command-based MCP servers configured",
+    };
+  }
+
+  if (broken.length === 0) {
+    return {
+      name: NAME,
+      status: "pass",
+      detail: `${checked} command${checked === 1 ? "" : "s"} resolve on PATH`,
+      band,
+    };
+  }
+
+  return {
+    name: NAME,
+    status: "fail",
+    detail: `${broken.length} of ${checked} unresolvable`,
+    items: broken,
+    remedy:
+      "Install the missing command or remove the entry — every agent session tries and fails to boot it.",
+    band,
+  };
+}

package/src/capabilities/doctor/checks/checkMcpConfigured.ts

@@ -0,0 +1,67 @@
+import type { DetectedHarness } from "@canonical/harnesses";
+import { detectHarnesses, readMcpConfig } from "@canonical/harnesses";
+import { runTask } from "@canonical/task/node";
+import type { CheckResult } from "../types.js";
+import { deriveBand } from "./deriveBand.js";
+
+/**
+ * Check that at least one AI harness has pragma configured as an MCP server. The
+ * result's band is derived from the harnesses actually found (Windsurf ⇒ global,
+ * Cursor ⇒ project), not the check name — so a global-scope harness is not
+ * mislabeled PROJECT.
+ *
+ * @param cwd - The project root to detect harnesses against.
+ * @returns A CheckResult listing configured harnesses, or fail with a remedy.
+ * @note Impure — detects harnesses and reads their MCP configs.
+ */
+export async function checkMcpConfigured(cwd: string): Promise<CheckResult> {
+  let detected: DetectedHarness[];
+  try {
+    detected = await runTask(detectHarnesses(cwd));
+  } catch {
+    return {
+      name: "MCP configured",
+      status: "fail",
+      detail: "harness detection failed",
+      remedy: "pragma setup mcp",
+    };
+  }
+
+  if (detected.length === 0) {
+    return {
+      name: "MCP configured",
+      status: "fail",
+      detail: "no AI harnesses detected",
+      remedy: "pragma setup mcp",
+    };
+  }
+
+  const configured: DetectedHarness[] = [];
+  for (const d of detected) {
+    if (!d.configExists) continue;
+    try {
+      const servers = await runTask(readMcpConfig(d.harness, cwd));
+      if ("pragma" in servers) configured.push(d);
+    } catch {
+      // Config unreadable — skip.
+    }
+  }
+
+  if (configured.length > 0) {
+    return {
+      name: "MCP configured",
+      status: "pass",
+      detail: configured.map((d) => d.harness.name).join(", "),
+      band: deriveBand(configured),
+    };
+  }
+
+  const names = detected.map((d) => d.harness.name).join(", ");
+  return {
+    name: "MCP configured",
+    status: "fail",
+    detail: `detected ${names} but pragma not configured`,
+    remedy: "pragma setup mcp",
+    band: deriveBand(detected),
+  };
+}

package/src/capabilities/doctor/checks/checkNodeVersion.ts

@@ -0,0 +1,25 @@
+import type { CheckResult } from "../types.js";
+
+const MIN_NODE_MAJOR = 20;
+
+/**
+ * Check that the Node.js major version is at least {@link MIN_NODE_MAJOR}.
+ *
+ * @returns A CheckResult with the current version and pass/fail status.
+ * @note Impure — reads `process.versions`.
+ */
+export async function checkNodeVersion(): Promise<CheckResult> {
+  const version = process.versions.node;
+  const major = Number.parseInt(version.split(".")[0] ?? "0", 10);
+
+  if (major >= MIN_NODE_MAJOR) {
+    return { name: "Node version", status: "pass", detail: `v${version}` };
+  }
+
+  return {
+    name: "Node version",
+    status: "fail",
+    detail: `v${version} (requires >= ${MIN_NODE_MAJOR})`,
+    remedy: `Install Node.js >= ${MIN_NODE_MAJOR}`,
+  };
+}

package/src/capabilities/doctor/checks/checkPackageRefs.ts

@@ -0,0 +1,73 @@
+/**
+ * Doctor check: report how each configured semantic package resolves.
+ *
+ * ADAPTED for v2: the old local>git>bundled loader chain is retired — resolution
+ * now flows through `sources update` into `pragma.lock.json` + the cached pack.
+ * This check reads the lock (which packages resolved) and the storeless pack
+ * index (the entity total), never booting the store. An absent lock with
+ * configured packages is the "run `sources update`" case.
+ */
+
+import {
+  entityTotal,
+  readPackIndex,
+} from "../../../kernel/completion/entitySource.js";
+import type { PackageEntry } from "../../../kernel/config/types.js";
+import { readLock } from "../../../kernel/runtime/lock.js";
+import type { PragmaRuntime } from "../../../kernel/runtime/types.js";
+import type { CheckItem, CheckResult } from "../types.js";
+
+const entryName = (entry: PackageEntry): string =>
+  typeof entry === "string" ? entry : entry.name;
+
+/**
+ * Report package resolution status against the lock and the entity total.
+ *
+ * @param rt - The per-invocation runtime.
+ * @returns A CheckResult with a per-package breakdown.
+ * @note Impure — reads config, the lock, and the pack index from disk.
+ */
+export async function checkPackageRefs(
+  rt: PragmaRuntime,
+): Promise<CheckResult> {
+  const entries = (await rt.loadConfig()).config.packages ?? [];
+  const lock = readLock(rt.cwd);
+  const index = readPackIndex(rt.cwd);
+  const totalEntities = index ? entityTotal(index) : 0;
+
+  if (entries.length === 0) {
+    return {
+      name: "package refs",
+      status: "pass",
+      detail: `no packages configured — the embedded pack answers reads (${totalEntities.toLocaleString()} entities)`,
+    };
+  }
+
+  const items: CheckItem[] = [];
+  let unresolved = 0;
+  for (const entry of entries) {
+    const name = entryName(entry);
+    const packEntry = lock?.packs.find((pack) => pack.name === name);
+    if (packEntry) {
+      items.push({
+        label: name,
+        status: "pass",
+        detail: `resolved ${packEntry.resolved}`,
+      });
+    } else {
+      items.push({ label: name, status: "fail", detail: "not in the lock" });
+      unresolved += 1;
+    }
+  }
+
+  const ok = lock !== undefined && unresolved === 0;
+  return {
+    name: "package refs",
+    status: ok ? "pass" : "fail",
+    detail: ok
+      ? `${entries.length} package(s) resolved · ${totalEntities.toLocaleString()} entities`
+      : `${unresolved} of ${entries.length} package(s) not resolved`,
+    items,
+    ...(ok ? {} : { remedy: "pragma sources update" }),
+  };
+}

package/src/capabilities/doctor/checks/checkPragmaVersion.ts

@@ -0,0 +1,22 @@
+import type { PragmaRuntime } from "../../../kernel/runtime/types.js";
+import { detectInstallSource } from "../../shared/packageManager.js";
+import type { CheckResult } from "../types.js";
+
+/**
+ * Report the pragma version and how it was installed. Always passes — purely
+ * informational.
+ *
+ * @param rt - The per-invocation runtime (for `version`).
+ * @returns A CheckResult with version and install details.
+ * @note Impure — reads the process for the install heuristic.
+ */
+export async function checkPragmaVersion(
+  rt: PragmaRuntime,
+): Promise<CheckResult> {
+  const install = detectInstallSource();
+  return {
+    name: "pragma version",
+    status: "pass",
+    detail: `v${rt.version} (installed via ${install.label})`,
+  };
+}

package/src/capabilities/doctor/checks/checkShellCompletions.test.ts

@@ -0,0 +1,111 @@
+/**
+ * `checkShellCompletions` — the doctor check that verifies completions are
+ * installed AND functional.
+ *
+ * Runs against an isolated HOME and a controlled `$SHELL` so the three gates —
+ * the resolver effect test, the real install-path probe, and the zsh fpath
+ * activation gate — are deterministic. The effect test (gate 1) drives the real
+ * `runComplete` resolver; the install/fpath gates write real files under the
+ * temp HOME rather than mocking the fs.
+ */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { completionScriptPath } from "../../setup/shell.js";
+import { checkShellCompletions } from "./checkShellCompletions.js";
+
+const roots: string[] = [];
+const tmp = (): string => {
+  const dir = mkdtempSync(join(tmpdir(), "pragma-completions-"));
+  roots.push(dir);
+  return dir;
+};
+
+let prevHome: string | undefined;
+let prevShell: string | undefined;
+beforeEach(() => {
+  prevHome = process.env.HOME;
+  prevShell = process.env.SHELL;
+  process.env.HOME = tmp();
+});
+afterEach(() => {
+  process.env.HOME = prevHome;
+  if (prevShell === undefined) delete process.env.SHELL;
+  else process.env.SHELL = prevShell;
+  for (const dir of roots) rmSync(dir, { recursive: true, force: true });
+  roots.length = 0;
+});
+
+/** Write the (empty) completion script to the shell's real install path. */
+function installScript(shell: "zsh" | "bash" | "fish"): void {
+  const path = completionScriptPath(shell);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, "# stub\n");
+}
+
+/** Write a `.zshrc` that puts ~/.zfunc on fpath. */
+function wireZfunc(): void {
+  writeFileSync(
+    join(process.env.HOME as string, ".zshrc"),
+    "fpath=(~/.zfunc $fpath)\nautoload -Uz compinit && compinit\n",
+  );
+}
+
+describe("checkShellCompletions — effect test (gate 1)", () => {
+  it("passes the resolver gate: `pragma <TAB>` resolves nouns", async () => {
+    // No shell → skip, but only AFTER the resolver answered — the detail proves
+    // the effect test ran and succeeded.
+    delete process.env.SHELL;
+    const result = await checkShellCompletions(tmp());
+    expect(result.status).toBe("skip");
+    expect(result.detail).toMatch(/resolver OK/);
+  });
+});
+
+describe("checkShellCompletions — install probe (gate 2)", () => {
+  it("fails when $SHELL is set but no script is installed", async () => {
+    process.env.SHELL = "/usr/bin/bash";
+    const result = await checkShellCompletions(tmp());
+    expect(result.status).toBe("fail");
+    expect(result.detail).toMatch(/not installed/);
+    expect(result.remedy).toBe("pragma setup completions");
+  });
+
+  it("passes for bash once the script exists at its real path", async () => {
+    process.env.SHELL = "/usr/bin/bash";
+    installScript("bash");
+    const result = await checkShellCompletions(tmp());
+    expect(result.status).toBe("pass");
+    expect(result.detail).toMatch(/bash installed and resolving/);
+  });
+
+  it("passes for fish once the script exists at its real path", async () => {
+    process.env.SHELL = "/usr/bin/fish";
+    installScript("fish");
+    const result = await checkShellCompletions(tmp());
+    expect(result.status).toBe("pass");
+  });
+});
+
+describe("checkShellCompletions — zsh fpath activation (gate 3)", () => {
+  it("fails when the zsh script is installed but ~/.zfunc is not on fpath", async () => {
+    process.env.SHELL = "/usr/bin/zsh";
+    installScript("zsh");
+    const result = await checkShellCompletions(tmp());
+    expect(result.status).toBe("fail");
+    expect(result.detail).toMatch(/not on your fpath/);
+    // The remedy IS the activation hint — the exact ~/.zshrc lines.
+    expect(result.remedy).toMatch(/fpath=\(~\/\.zfunc/);
+  });
+
+  it("passes once the zsh script is installed AND ~/.zfunc is on fpath", async () => {
+    process.env.SHELL = "/usr/bin/zsh";
+    installScript("zsh");
+    wireZfunc();
+    const result = await checkShellCompletions(tmp());
+    expect(result.status).toBe("pass");
+    expect(result.detail).toMatch(/zsh installed and resolving/);
+  });
+});

package/src/capabilities/doctor/checks/checkShellCompletions.ts

@@ -0,0 +1,131 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+  indexCompletionEnv,
+  runComplete,
+} from "../../../kernel/completion/index.js";
+import { capabilities } from "../../index.js";
+import {
+  activationHint,
+  completionScriptPath,
+  detectShell,
+} from "../../setup/shell.js";
+import type { CheckResult } from "../types.js";
+
+const NAME = "Shell completions";
+
+/**
+ * Whether the user's `.zshrc` puts `~/.zfunc` on `$fpath` — the activation step
+ * `setup completions` cannot perform for the user. zsh loads nothing from
+ * `~/.zfunc` unless it is on `fpath` before `compinit`, so an installed script
+ * with no fpath wiring is silently dead. A permissive check: any `fpath` line
+ * mentioning `.zfunc` counts (we can't parse ordering statically).
+ */
+function zfuncOnFpath(): boolean {
+  try {
+    const rc = readFileSync(join(homedir(), ".zshrc"), "utf-8");
+    return rc
+      .split("\n")
+      .some((line) => line.includes("fpath") && line.includes(".zfunc"));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Drive the storeless `__complete` resolver and observe that it answers — the
+ * completion effect the installed script delegates every name context to. Uses
+ * the noun context (`pragma <TAB>`), which is grammar-derived and never empty,
+ * so a zero here means the resolver itself is broken, independent of any pack.
+ *
+ * @param cwd - The project directory (wires the entity seam, though the noun
+ *   context does not read it).
+ * @returns The number of candidates the resolver returned for a bare `pragma `.
+ */
+async function completeProbe(cwd: string): Promise<number> {
+  const matches = await runComplete(
+    [""],
+    capabilities,
+    indexCompletionEnv(cwd),
+  );
+  return matches.length;
+}
+
+/**
+ * Check that shell completions are installed AND functional.
+ *
+ * Three gates, in order:
+ * 1. The resolver answers (`completeProbe` drives `runComplete` end to end) —
+ *    the effect every installed script depends on. A failure here is a real
+ *    regression, so it fails even when nothing is installed.
+ * 2. The script file exists at the shell's real install path (`shell.ts`) —
+ *    NOT a `"pragma"` substring in an RC file, which `setup completions` never
+ *    writes.
+ * 3. For zsh, `~/.zfunc` is on `$fpath` — the activation step setup can only
+ *    hint. Installed-but-unwired reports a distinct remedy.
+ *
+ * @param cwd - The project directory (for the resolver's entity seam).
+ * @returns A CheckResult: pass (installed + wired + answering), fail (with the
+ *   attributable remedy), or skip (shell undetected).
+ * @note Impure — reads `$SHELL`, the install path, `.zshrc`, and drives the
+ *   storeless resolver.
+ */
+export async function checkShellCompletions(cwd: string): Promise<CheckResult> {
+  // 1. Effect test: the resolver the scripts delegate to must actually answer.
+  let candidates: number;
+  try {
+    candidates = await completeProbe(cwd);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return {
+      name: NAME,
+      status: "fail",
+      detail: `completion resolver failed: ${reason}`,
+      remedy: "Report this as a bug — `pragma __complete` should never throw.",
+    };
+  }
+  if (candidates === 0) {
+    return {
+      name: NAME,
+      status: "fail",
+      detail: "completion resolver returned no candidates for `pragma <TAB>`",
+      remedy: "Report this as a bug — the noun context is always non-empty.",
+    };
+  }
+
+  // 2. The script file exists at the shell's real install path.
+  const shell = detectShell();
+  if (!shell) {
+    return {
+      name: NAME,
+      status: "skip",
+      detail: "resolver OK; shell not detected ($SHELL unset)",
+    };
+  }
+  const path = completionScriptPath(shell);
+  if (!existsSync(path)) {
+    return {
+      name: NAME,
+      status: "fail",
+      detail: `resolver OK; ${shell} script not installed`,
+      remedy: "pragma setup completions",
+    };
+  }
+
+  // 3. zsh only: the script is dead unless ~/.zfunc is on $fpath.
+  if (shell === "zsh" && !zfuncOnFpath()) {
+    return {
+      name: NAME,
+      status: "fail",
+      detail: `installed at ${path}, but ~/.zfunc is not on your fpath`,
+      remedy: activationHint("zsh"),
+    };
+  }
+
+  return {
+    name: NAME,
+    status: "pass",
+    detail: `${shell} installed and resolving (${candidates} nouns)`,
+  };
+}

package/src/capabilities/doctor/checks/checkSkillsSymlinked.ts

@@ -0,0 +1,60 @@
+import { existsSync } from "node:fs";
+import type { DetectedHarness } from "@canonical/harnesses";
+import { detectHarnesses } from "@canonical/harnesses";
+import { runTask } from "@canonical/task/node";
+import type { CheckResult } from "../types.js";
+
+/**
+ * Check that a skills directory exists for each detected AI harness. Skipped
+ * when no harnesses are detected.
+ *
+ * @param cwd - The project root to detect harnesses against.
+ * @returns A CheckResult indicating pass, fail (with a remedy), or skip.
+ * @note Impure — detects harnesses and probes the filesystem.
+ */
+export async function checkSkillsSymlinked(cwd: string): Promise<CheckResult> {
+  let detected: DetectedHarness[];
+  try {
+    detected = await runTask(detectHarnesses(cwd));
+  } catch {
+    return {
+      name: "Skills symlinked",
+      status: "fail",
+      detail: "harness detection failed",
+      remedy: "pragma setup skills",
+    };
+  }
+
+  if (detected.length === 0) {
+    return {
+      name: "Skills symlinked",
+      status: "skip",
+      detail: "no AI harnesses detected",
+    };
+  }
+
+  const linked: string[] = [];
+  const missing: string[] = [];
+  for (const d of detected) {
+    if (existsSync(d.harness.skillsPath(cwd))) {
+      linked.push(d.harness.name);
+    } else {
+      missing.push(d.harness.name);
+    }
+  }
+
+  if (missing.length === 0) {
+    return {
+      name: "Skills symlinked",
+      status: "pass",
+      detail: linked.join(", "),
+    };
+  }
+
+  return {
+    name: "Skills symlinked",
+    status: "fail",
+    detail: `missing for ${missing.join(", ")}`,
+    remedy: "pragma setup skills",
+  };
+}

package/src/capabilities/doctor/checks/deriveBand.test.ts

@@ -0,0 +1,42 @@
+/**
+ * `deriveBand` — band a doctor check by the harnesses it actually found.
+ *
+ * Fixtures wrap REAL harness definitions (via `findHarnessById`, no casts), so
+ * the scope→band mapping is exercised against the true `scope` fields: the
+ * regression this guards is a global-scope harness (Windsurf) being mislabeled
+ * PROJECT by a static per-name guess.
+ */
+
+import type { DetectedHarness } from "@canonical/harnesses";
+import { findHarnessById } from "@canonical/harnesses";
+import { describe, expect, it } from "vitest";
+import { deriveBand } from "./deriveBand.js";
+
+/** A minimal {@link DetectedHarness} over a real definition (no `as` casts). */
+function detect(id: string): DetectedHarness {
+  const harness = findHarnessById(id);
+  if (!harness) throw new Error(`unknown harness fixture: ${id}`);
+  return { harness, confidence: "high", configExists: true, configPath: "x" };
+}
+
+describe("deriveBand", () => {
+  it("bands a project-scope harness (Cursor) as project", () => {
+    expect(deriveBand([detect("cursor")])).toBe("project");
+  });
+
+  it("bands a global-scope harness (Windsurf) as global — the fixed mislabel", () => {
+    expect(deriveBand([detect("windsurf")])).toBe("global");
+  });
+
+  it("bands a dual-scope harness (Claude Code) by its default band (project)", () => {
+    expect(deriveBand([detect("claude-code")])).toBe("project");
+  });
+
+  it("leaves a set spanning BOTH bands unbanded (general, not mislabeled)", () => {
+    expect(deriveBand([detect("cursor"), detect("windsurf")])).toBeUndefined();
+  });
+
+  it("leaves an empty set unbanded", () => {
+    expect(deriveBand([])).toBeUndefined();
+  });
+});

package/src/capabilities/doctor/checks/deriveBand.ts

@@ -0,0 +1,28 @@
+/**
+ * Derive a doctor check's config band from the harnesses it actually found,
+ * rather than a static per-check-name guess. The aggregate MCP checks read each
+ * harness's DEFAULT-band file (`defaultBandOf` — the home config for a
+ * global-only harness like Windsurf, the project file otherwise), so the band a
+ * finding belongs to is exactly that default band.
+ */
+
+import type { DetectedHarness } from "@canonical/harnesses";
+import { defaultBandOf } from "@canonical/harnesses";
+import type { ScopeBand } from "../types.js";
+
+/**
+ * The single config band a set of detected harnesses shares, or `undefined` when
+ * the set is empty or genuinely spans BOTH bands. A two-band finding stays
+ * unbanded (rendered in the general section) instead of being mislabeled as one
+ * band — faithful to the two-band model: band by what was found, never a guess.
+ *
+ * @param harnesses - The detected harnesses the check reports on.
+ * @returns The shared {@link ScopeBand}, or `undefined` when none/mixed.
+ */
+export function deriveBand(
+  harnesses: readonly DetectedHarness[],
+): ScopeBand | undefined {
+  const bands = new Set<ScopeBand>();
+  for (const detected of harnesses) bands.add(defaultBandOf(detected.harness));
+  return bands.size === 1 ? bands.values().next().value : undefined;
+}