@monster-orange/den 0.2.6 → 0.2.8

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

@@ -0,0 +1,172 @@
+/**
+ * `<cli> org list` (ORG-1a): every org with its label, its workspaces on
+ * this machine, whether it is the default (`github_org`), and the org
+ * warnings (C1). The orgs are `/api/orgs`'s (catalog owners plus `orgs:`),
+ * then the default org and any workspace's org that list does not name.
+ *
+ * `--org <id>` (on `org list` and `workspace list`) keeps one org's rows.
+ */
+import chalk from "chalk";
+import { product } from "../../shared/product.js";
+import { listOrgs } from "../../shared/manifest/service-links.js";
+import { githubOwnersOf } from "../../shared/org-sources.js";
+import { readDenConfig } from "../../shared/den-config.js";
+import { isConfigError } from "../../shared/config-error.js";
+import {
+  defaultOrg,
+  githubOrgFor,
+  readOrgContext,
+  resolveAllWorkspaceOrgs,
+  withOrgMembership,
+  type OrgContext,
+  type WorkspaceOrg,
+} from "../../shared/environment-manager/workspace-org.js";
+import { newTable } from "./table.js";
+
+/** `--org <id>`'s value from `args` (also `--org=<id>`), or undefined. */
+export function orgFlag(args: readonly string[]): string | undefined {
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--org") return args[i + 1];
+    if (a.startsWith("--org=")) return a.slice("--org=".length);
+  }
+  return undefined;
+}
+
+/** `args` without `--org <id>` / `--org=<id>`. */
+export function withoutOrgFlag(args: readonly string[]): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--org") {
+      i++;
+      continue;
+    }
+    if (args[i].startsWith("--org=")) continue;
+    out.push(args[i]);
+  }
+  return out;
+}
+
+export const sameOrg = (a: string | null, b: string): boolean =>
+  a !== null && a.toLowerCase() === b.toLowerCase();
+
+export interface OrgListRow {
+  id: string;
+  label: string;
+  default: boolean;
+  workspaces: string[];
+}
+
+/** The rows `org list` prints, and every workspace's warnings. */
+export function orgListRows(ctx: OrgContext = readOrgContext()): {
+  rows: OrgListRow[];
+  warnings: string[];
+  resolved: WorkspaceOrg[];
+} {
+  const resolved = resolveAllWorkspaceOrgs(ctx);
+  const listed = withOrgMembership(
+    listOrgs(ctx.catalog, ctx.config.orgs ?? {}),
+    resolved,
+    ctx.file,
+    ctx.config,
+  ).map((o) => ({
+    id: o.id,
+    label: o.label,
+    default: o.default,
+    workspaces: o.workspaces,
+  }));
+  const local = new Set(Object.keys(ctx.file.workspaces));
+  const extra = new Map<string, OrgListRow>();
+  const add = (id: string, isDefault: boolean): void => {
+    if (listed.some((r) => sameOrg(r.id, id))) return;
+    const key = id.toLowerCase();
+    if (!extra.has(key))
+      extra.set(key, { id, label: id, default: isDefault, workspaces: [] });
+  };
+  const d = defaultOrg(ctx.config);
+  if (d) add(d, true);
+  for (const w of resolved)
+    if (w.org && local.has(w.workspace)) {
+      add(w.org, sameOrg(d, w.org));
+      extra.get(w.org.toLowerCase())?.workspaces.push(w.workspace);
+    }
+  return {
+    rows: [...listed, ...extra.values()],
+    warnings: resolved
+      .filter((w) => local.has(w.workspace))
+      .flatMap((w) => w.warnings),
+    resolved,
+  };
+}
+
+/**
+ * The GitHub org `register` lists repos from: `--org <id>`, else the
+ * workspace's resolved org. Never Den's own checkout or remote (SEC-0).
+ * Undefined when there is none, or it is not a GitHub owner name.
+ */
+export function registerOrg(
+  workspace: string,
+  orgArg?: string,
+  ctx?: OrgContext,
+): string | undefined {
+  let org = orgArg?.trim();
+  if (org) {
+    // ORG-1d: an org id names its first GitHub source's owner; an org with
+    // no GitHub source has nothing to list.
+    org = githubOwnersOf(org, (ctx?.config ?? readDenConfig()).orgs)[0];
+    if (!org) return undefined;
+  } else {
+    try {
+      org = githubOrgFor(workspace, ctx);
+    } catch (e) {
+      // No org is "nothing to register"; a config that fails validation is not.
+      if (isConfigError(e)) throw e;
+      return undefined;
+    }
+  }
+  return /^[A-Za-z0-9][A-Za-z0-9-]*$/.test(org) ? org : undefined;
+}
+
+/** Print the org warnings under a listing. */
+export function printOrgWarnings(warnings: readonly string[]): void {
+  for (const w of warnings) console.log(chalk.yellow(`  ⚠ ${w}`));
+  if (warnings.length) console.log();
+}
+
+export function cmdOrg(args: string[]): void {
+  const sub = args[0] ?? "list";
+  if (sub !== "list") {
+    console.log(chalk.red(`Usage: ${product().cli} org list [--org <id>]`));
+    process.exitCode = 1;
+    return;
+  }
+  const only = orgFlag(args.slice(1));
+  const { rows, warnings, resolved } = orgListRows();
+  const shown = only ? rows.filter((r) => sameOrg(r.id, only)) : rows;
+  const table = newTable({
+    head: ["Org", "Label", "Default", "Workspaces"],
+    style: { head: ["cyan"] },
+  });
+  for (const r of shown)
+    table.push([
+      chalk.bold(r.id),
+      r.label,
+      r.default ? chalk.green("✓") : "",
+      r.workspaces.join(", ") || chalk.gray("none"),
+    ]);
+  console.log(table.toString());
+  if (only && shown.length === 0)
+    console.log(chalk.yellow(`  No org ${only}.`));
+  const inScope = only
+    ? new Set(
+        resolved.filter((w) => sameOrg(w.org, only)).map((w) => w.workspace),
+      )
+    : null;
+  printOrgWarnings(
+    inScope
+      ? warnings.filter((w) =>
+          [...inScope].some((n) => w.startsWith(`workspace ${n}:`)),
+        )
+      : warnings,
+  );
+}

package/src/ui/cli/results-viewer.ts

@@ -3,7 +3,7 @@
  * Display test results in CLI
  */
 
-import Table from "cli-table3";
+import { newTable } from "./table.js";
 import chalk from "chalk";
 import { resultReader } from "../../shared/results/result-reader.js";
 import type {
@@ -40,7 +40,7 @@ export class ResultsViewer {
     for (const pillar of pillars) {
       console.log(chalk.bold(`\n${this.formatPillarName(pillar)}:`));
 
-      const table = new Table({
+      const table = newTable({
         head: [
           chalk.cyan("Environment"),
           chalk.cyan("Total"),
@@ -115,7 +115,7 @@ export class ResultsViewer {
       return;
     }
 
-    const table = new Table({
+    const table = newTable({
       head: [
         chalk.cyan("Test"),
         chalk.cyan("Status"),
@@ -191,7 +191,7 @@ export class ResultsViewer {
       return;
     }
 
-    const table = new Table({
+    const table = newTable({
       head: [
         chalk.cyan("Journey"),
         chalk.cyan("Verdict"),
@@ -281,7 +281,7 @@ export class ResultsViewer {
       return;
     }
 
-    const table = new Table({
+    const table = newTable({
       head: [
         chalk.cyan("Test"),
         chalk.cyan("Runs"),

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/up-args.ts

@@ -0,0 +1,15 @@
+/**
+ * `up -w <ws>` with no repo, no `-a` and no service repo under the cwd
+ * (0.2.8-dev.1). `-w` only picks the workspace; it does not say what in it
+ * to start, so the plan used to come back "No services specified and no
+ * invocation target resolvable". It is a usage error naming the two forms
+ * that do: a repo, or `-a` for the whole workspace.
+ */
+export function upNeedsTarget(cli: string, ws: string, plan: boolean): string {
+  const name = /^[A-Za-z0-9._-]{1,64}$/.test(ws) ? ws : "<workspace>";
+  const p = plan ? " --plan" : "";
+  return (
+    `up -w ${name} needs what to start: \`${cli} up -a${p} -w ${name}\` ` +
+    `for the whole workspace, or \`${cli} up <repo>${p} -w ${name}\` for one repo and its dependencies.`
+  );
+}

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/mcp/scope.ts

@@ -0,0 +1,277 @@
+/**
+ * A scoped MCP server (AG-2a-core): `<cli> mcp --workspace <ws> --actor
+ * agent:<id>`. It pins one workspace, refuses any call that names another,
+ * filters lists to it, and stamps the actor on every web API call (the
+ * x-den-mcp-agent / x-den-mcp-workspace headers, see shared/agent-actor.ts).
+ *
+ * It binds cooperating agents only: the scope lives in this process, and the
+ * web server's HTTP API does not check it yet (WS-3a).
+ */
+import * as path from "path";
+import { AGENT_ACTOR_RE, WORKSPACE_NAME_RE } from "../../shared/agent-actor.js";
+import type { DenApi } from "./api.js";
+import { Refusal } from "./guards.js";
+
+export interface McpScope {
+  /** The one workspace this server serves. */
+  workspace: string;
+  /** Who acts: `agent:<id>`. */
+  actor: string;
+}
+
+/** A call reached outside the scoped workspace. Always reported (F2). */
+export class ScopeRefusal extends Refusal {
+  constructor(message: string) {
+    super(message);
+    this.name = "ScopeRefusal";
+  }
+}
+
+/** `--workspace` / `--actor` were given wrongly: a usage error (exit 2). */
+export class ScopeUsageError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ScopeUsageError";
+  }
+}
+
+const FLAGS: Record<string, "workspace" | "actor"> = {
+  "--workspace": "workspace",
+  "-w": "workspace",
+  "--actor": "actor",
+};
+
+/**
+ * Take `--workspace <ws>` (or `-w`) and `--actor agent:<id>` out of `argv`,
+ * also in the `--flag=value` form. Both or neither: a scope without an actor
+ * would act unattributed, an actor without a scope would look bound when it
+ * is not. Returns the scope (null when neither is given) and the rest of
+ * argv, unchanged otherwise.
+ */
+export function parseScopeFlags(argv: readonly string[]): {
+  scope: McpScope | null;
+  rest: string[];
+} {
+  const got: Partial<Record<"workspace" | "actor", string>> = {};
+  const rest: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const eq = a.indexOf("=");
+    const name = a.startsWith("-") && eq !== -1 ? a.slice(0, eq) : a;
+    const key = FLAGS[name];
+    if (!key) {
+      rest.push(a);
+      continue;
+    }
+    let value: string | undefined;
+    if (name !== a) value = a.slice(eq + 1);
+    else {
+      value = argv[i + 1];
+      if (value === undefined || value.startsWith("-"))
+        throw new ScopeUsageError(`${name} needs a value`);
+      i++;
+    }
+    if (got[key] !== undefined && got[key] !== value)
+      throw new ScopeUsageError(`--${key} given twice`);
+    got[key] = value;
+  }
+  if (got.workspace === undefined && got.actor === undefined)
+    return { scope: null, rest };
+  if (got.workspace === undefined)
+    throw new ScopeUsageError(
+      "--actor needs --workspace: a scoped server serves one workspace",
+    );
+  if (got.actor === undefined)
+    throw new ScopeUsageError(
+      "--workspace needs --actor agent:<id>: a scoped server says who acts",
+    );
+  if (!WORKSPACE_NAME_RE.test(got.workspace))
+    throw new ScopeUsageError(
+      `--workspace "${printable(got.workspace)}" is not a workspace name ` +
+        "(letters, digits, dots, dashes, underscores; at most 64)",
+    );
+  if (!AGENT_ACTOR_RE.test(got.actor))
+    throw new ScopeUsageError(
+      `--actor "${printable(got.actor)}" is not agent:<id> ` +
+        "(the id: letters, digits, dots, dashes, underscores; at most 64)",
+    );
+  return { scope: { workspace: got.workspace, actor: got.actor }, rest };
+}
+
+/** A value echoed back in an error: one printable line, bounded. */
+function printable(v: string): string {
+  return v.replace(/[^\x20-\x7e]/g, "?").slice(0, 80);
+}
+
+/** The refusal for a call that names `other`. */
+export function otherWorkspace(
+  tool: string,
+  scope: McpScope,
+  other: string,
+): ScopeRefusal {
+  return new ScopeRefusal(
+    `${tool}: this MCP server is scoped to workspace "${scope.workspace}" ` +
+      `(${scope.actor}); "${printable(other)}" is another workspace, so nothing was read or run.`,
+  );
+}
+
+/**
+ * A tool's arguments with the workspace pinned: absent, it becomes the
+ * scoped one; another one is refused before anything is asked of the API.
+ */
+export function pinWorkspace(
+  tool: string,
+  args: Record<string, unknown>,
+  scope: McpScope,
+): Record<string, unknown> {
+  const ws = args.workspace;
+  if (ws !== undefined && ws !== null && ws !== "" && ws !== scope.workspace)
+    throw otherWorkspace(tool, scope, String(ws));
+  return { ...args, workspace: scope.workspace };
+}
+
+/** What /api/workspaces answers (the fields the scope reads). */
+interface WorkspacesBody {
+  active?: unknown;
+  focus?: unknown;
+  workspaces?: unknown;
+  [k: string]: unknown;
+}
+
+const asRecord = (v: unknown): Record<string, unknown> =>
+  v && typeof v === "object" && !Array.isArray(v)
+    ? (v as Record<string, unknown>)
+    : {};
+
+/**
+ * /api/workspaces narrowed to the scoped workspace: only its entry, its
+ * resolved directory and code-workspace path, `active` holding it or empty,
+ * and `focus` only when it is the focus. Everything else is left out.
+ */
+export function filterWorkspacesBody(
+  body: unknown,
+  scope: McpScope,
+): Record<string, unknown> {
+  const b = asRecord(body) as WorkspacesBody;
+  const ws = scope.workspace;
+  const only = (v: unknown): Record<string, unknown> => {
+    const r = asRecord(v);
+    return ws in r ? { [ws]: r[ws] } : {};
+  };
+  return {
+    active: Array.isArray(b.active) ? b.active.filter((n) => n === ws) : [],
+    ...(b.focus === ws ? { focus: ws } : {}),
+    workspaces: only(b.workspaces),
+    ...(b.resolvedDirs !== undefined
+      ? { resolvedDirs: only(b.resolvedDirs) }
+      : {}),
+    ...(b.codeWorkspacePaths !== undefined
+      ? { codeWorkspacePaths: only(b.codeWorkspacePaths) }
+      : {}),
+    scope: { workspace: ws, actor: scope.actor },
+  };
+}
+
+/** The workspace /api/workspaces says is focused (focus, else active[0]). */
+function focusedOf(body: unknown): string | null {
+  const b = asRecord(body) as WorkspacesBody;
+  if (typeof b.focus === "string" && b.focus) return b.focus;
+  if (Array.isArray(b.active) && typeof b.active[0] === "string")
+    return b.active[0];
+  return null;
+}
+
+/**
+ * Throws unless the scoped workspace exists in this distribution. A missing
+ * one must not fall through to the web server's "no workspace" defaults,
+ * which list services outside any workspace.
+ */
+export async function assertScopeExists(
+  api: DenApi,
+  scope: McpScope,
+): Promise<unknown> {
+  const body = await api.get("/api/workspaces");
+  if (!(scope.workspace in asRecord(asRecord(body).workspaces)))
+    throw new ScopeRefusal(
+      `this MCP server is scoped to workspace "${scope.workspace}", which does not exist in this distribution.`,
+    );
+  return body;
+}
+
+/**
+ * Tests run against the focused workspace (the web server has no workspace
+ * argument for them): a scoped server runs or lists them only when that is
+ * its own.
+ */
+export async function assertScopeFocused(
+  tool: string,
+  api: DenApi,
+  scope: McpScope,
+): Promise<void> {
+  const focused = focusedOf(await api.get("/api/workspaces"));
+  if (focused !== scope.workspace)
+    throw new ScopeRefusal(
+      `${tool}: tests run against the focused workspace` +
+        `${focused ? ` ("${focused}")` : ""}, and this MCP server is scoped to ` +
+        `"${scope.workspace}". Focus "${scope.workspace}" first; nothing was read or run.`,
+    );
+}
+
+/** The fields of an /api/services entry the scope checks read. */
+interface ScopedEntry {
+  repo?: unknown;
+  service?: unknown;
+  repoPath?: unknown;
+}
+
+async function scopedEntries(
+  api: DenApi,
+  scope: McpScope,
+): Promise<ScopedEntry[]> {
+  const list = await api.get("/api/services", {
+    env: "local",
+    workspace: scope.workspace,
+  });
+  return Array.isArray(list) ? (list as ScopedEntry[]) : [];
+}
+
+/** Every `repo/service` must be one of the scoped workspace's services. */
+export async function assertServicesInScope(
+  tool: string,
+  api: DenApi,
+  scope: McpScope,
+  targets: readonly { repo: string; service: string }[],
+): Promise<void> {
+  const entries = await scopedEntries(api, scope);
+  const have = new Set(entries.map((e) => `${e.repo}/${e.service}`));
+  const outside = targets
+    .map((t) => `${t.repo}/${t.service}`)
+    .filter((t) => !have.has(t));
+  if (outside.length)
+    throw new ScopeRefusal(
+      `${tool}: ${outside.map(printable).join(", ")} ${outside.length === 1 ? "is" : "are"} not a service ` +
+        `of workspace "${scope.workspace}", the only one this MCP server serves; nothing was read.`,
+    );
+}
+
+/** A manifest path must be absolute and inside one of the workspace's repos. */
+export async function assertPathInScope(
+  tool: string,
+  api: DenApi,
+  scope: McpScope,
+  p: string,
+): Promise<void> {
+  if (!path.isAbsolute(p))
+    throw new ScopeRefusal(
+      `${tool}: a scoped MCP server takes an absolute path inside workspace "${scope.workspace}"'s repos (or the manifest content).`,
+    );
+  const target = path.resolve(p);
+  const roots = (await scopedEntries(api, scope))
+    .map((e) => e.repoPath)
+    .filter((r): r is string => typeof r === "string" && r.length > 0)
+    .map((r) => path.resolve(r));
+  if (!roots.some((r) => target === r || target.startsWith(r + path.sep)))
+    throw new ScopeRefusal(
+      `${tool}: ${printable(p)} is not inside a repo of workspace "${scope.workspace}", the only one this MCP server serves; nothing was read.`,
+    );
+}