@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/kernel/project/mcp/registerVerb.ts

@@ -0,0 +1,296 @@
+/**
+ * Adapter: {@link VerbSpec} → an MCP tool.
+ *
+ * This is the one seam where the grammar meets the MCP SDK — the only place a
+ * projector reaches for zod (to build the input schema the SDK validates). The
+ * tool name follows the grammar's naming rule, annotations derive from the
+ * capability, and a mutating verb gains the plan-first `confirm` flow: without
+ * `confirm`, the verb's `Task` is dry-run and a plan is returned
+ * (`{ planOnly: true, confirmRequired: true }`); with `confirm: true`, it runs
+ * for real.
+ */
+
+import { statSync } from "node:fs";
+import { isAbsolute } from "node:path";
+import { describeEffect, dryRun, type Task } from "@canonical/task";
+import { runTask } from "@canonical/task/node";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { asPragmaError } from "../../error/fromTaskError.js";
+import { PragmaError } from "../../error/PragmaError.js";
+import type { InteractionRuntime, PragmaRuntime } from "../../runtime/types.js";
+import { toolName } from "../../spec/emitSurface.js";
+import type { McpAnnotations, ParamSpec, VerbSpec } from "../../spec/types.js";
+import { toolError, toolSuccess } from "./envelope.js";
+
+/**
+ * Resolve the effective per-call write root for a mutating tool call.
+ *
+ * The MCP-only injected `cwd` arg lets an agent target a project directory other
+ * than the server's launch dir. It MUST be an absolute, existing directory —
+ * this is the SINGLE cwd the SEC-2 jail validates AND the interpreter resolves
+ * effect paths against, so a write dir the jail never checked can never exist.
+ *
+ * @throws PragmaError INVALID_INPUT for a relative or non-directory `cwd`.
+ */
+function resolveEffectiveCwd(rawCwd: unknown, fallback: string): string {
+  if (typeof rawCwd !== "string" || rawCwd === "") return fallback;
+  if (!isAbsolute(rawCwd)) {
+    throw PragmaError.invalidInput("cwd", rawCwd, {
+      recovery: { message: "Provide an absolute project directory path." },
+    });
+  }
+  let isDir = false;
+  try {
+    isDir = statSync(rawCwd).isDirectory();
+  } catch {
+    isDir = false;
+  }
+  if (!isDir) {
+    throw PragmaError.invalidInput("cwd", rawCwd, {
+      recovery: { message: "The cwd must be an existing directory." },
+    });
+  }
+  return rawCwd;
+}
+
+/** The base zod type for a param, before `.describe()`/`.optional()`. */
+function zodForParam(param: ParamSpec): z.ZodTypeAny {
+  switch (param.kind) {
+    case "string":
+      return z.string();
+    case "number":
+      return z.number();
+    case "boolean":
+      return z.boolean();
+    case "enum":
+      return z.enum(param.values as unknown as [string, ...string[]]);
+    case "string[]":
+      return z.array(z.string());
+  }
+}
+
+/**
+ * Build the zod input shape for a verb's params.
+ *
+ * Each param becomes a described field; non-required params are optional. The
+ * returned raw shape is what the MCP SDK validates tool arguments against.
+ *
+ * @param params - The verb's parameter specs.
+ * @returns A zod raw shape keyed by param name.
+ */
+export function buildZodSchema(params: readonly ParamSpec[]): z.ZodRawShape {
+  const shape: z.ZodRawShape = {};
+  for (const param of params) {
+    let field = zodForParam(param);
+    if (param.doc) field = field.describe(param.doc);
+    // Apply a declared default so the MCP schema matches the CLI, which fills
+    // ParamSpec.default when a flag is omitted (dispatch.extractParams).
+    if ("default" in param && param.default !== undefined) {
+      field = field.default(param.default);
+    } else if (!param.required) {
+      field = field.optional();
+    }
+    shape[param.name] = field;
+  }
+  return shape;
+}
+
+/** Derive the MCP annotations for a verb from its capability. */
+function annotationsFor(verb: VerbSpec): McpAnnotations {
+  return {
+    readOnlyHint: !verb.capability.mutates,
+    ...(verb.capability.destructive !== undefined
+      ? { destructiveHint: verb.capability.destructive }
+      : {}),
+    openWorldHint: false,
+  };
+}
+
+/** Pick just the verb's declared params out of the parsed tool arguments. */
+function paramsFromArgs(
+  verb: VerbSpec,
+  args: Record<string, unknown>,
+): Record<string, unknown> {
+  const params: Record<string, unknown> = {};
+  for (const param of verb.params) {
+    if (param.name in args) params[param.name] = args[param.name];
+  }
+  return params;
+}
+
+/**
+ * Apply the injected `detail` argument to a per-call runtime.
+ *
+ * A verb with a {@link DisclosureSpec} gains a `detail` enum tool param (see
+ * {@link registerVerb}); when the agent sets it, this seeds `globalFlags.detail`
+ * for THIS call so the verb's `run` resolves the level through the same uniform
+ * `resolveDetail` the CLI `--detail` flag feeds — no VerbSpec field, no
+ * Formatters-signature change, no MCP-opts-out asymmetry.
+ */
+function withDetail(
+  verb: VerbSpec,
+  runtime: PragmaRuntime,
+  args: Record<string, unknown>,
+): PragmaRuntime {
+  if (!verb.disclosure || typeof args.detail !== "string") return runtime;
+  return {
+    ...runtime,
+    globalFlags: { ...runtime.globalFlags, detail: args.detail as never },
+  };
+}
+
+/** The tool handler for a read verb: run, project, envelope. */
+function readHandler(verb: VerbSpec, runtime: PragmaRuntime) {
+  return async (args: Record<string, unknown>): Promise<CallToolResult> => {
+    try {
+      if (verb.capability.needsStore) await runtime.store.get();
+      const params = paramsFromArgs(verb, args);
+      const result = await Promise.resolve(
+        verb.run(params, withDetail(verb, runtime, args)) as Promise<unknown>,
+      );
+      return toolSuccess(JSON.parse(verb.output.formatters.json(result)));
+    } catch (error) {
+      return toolError(asPragmaError(error));
+    }
+  };
+}
+
+/**
+ * Route a Task's log effects to STDERR. The default interpreter logs to
+ * `console.log` (stdout), which would corrupt the MCP stdio JSON-RPC frame;
+ * diagnostics belong on stderr. Mirrors the CLI dispatcher's `logToStderr`.
+ */
+const logToStderr = (_level: string, message: string): void => {
+  process.stderr.write(`${message}\n`);
+};
+
+/** The tool handler for a mutating verb: plan-first unless `confirm: true`. */
+function mutateHandler(verb: VerbSpec, runtime: PragmaRuntime) {
+  return async (args: Record<string, unknown>): Promise<CallToolResult> => {
+    try {
+      // The SINGLE per-call write root: validated here (absolute + existing dir)
+      // and threaded as `rt.cwd`, so the SEC-2 jail and the interpreter's
+      // effect-path base are literally the same value — no jail bypass.
+      const effectiveCwd = resolveEffectiveCwd(args.cwd, runtime.cwd);
+      if (verb.capability.needsStore) await runtime.store.get();
+      const params = paramsFromArgs(verb, args);
+      // Without `confirm`, this is a plan-only preview: tell the verb so a
+      // network-touching mutation stays offline and never fetches on discovery.
+      const preview = args.confirm !== true;
+      // MCP has no interactive channel: transport "mcp" makes an interactive
+      // verb pick the params-or-error prompt strategy, so a tool call can never
+      // hang waiting for input.
+      const interaction: InteractionRuntime = {
+        isTTY: false,
+        transport: "mcp",
+        yes: args.confirm === true,
+      };
+      const mutationRuntime: PragmaRuntime = {
+        ...runtime,
+        cwd: effectiveCwd,
+        mutation: { preview },
+        interaction,
+      };
+      const task = await Promise.resolve(
+        verb.run(params, mutationRuntime) as
+          | Task<unknown>
+          | Promise<Task<unknown>>,
+      );
+      if (preview) {
+        const plan = dryRun(task)
+          .effects.filter((effect) => effect._tag !== "Prompt")
+          .map(describeEffect);
+        return toolSuccess({ plan }, { planOnly: true, confirmRequired: true });
+      }
+      // Real execution: spread the verb's runner options (prompt handler,
+      // stamping) into the interpreter; run teardown afterwards.
+      const exec = mutationRuntime.exec ?? {};
+      try {
+        const result = await runTask(task, { onLog: logToStderr, ...exec });
+        return toolSuccess(JSON.parse(verb.output.formatters.json(result)));
+      } finally {
+        // A real mutation may have changed the pack/config on disk. This runtime
+        // is booted ONCE for the whole server lifetime and shared by every tool,
+        // so drop its server-lifetime caches (store session + the config memo the
+        // boot depends on) FIRST — before teardown, so a throwing `dispose` can
+        // never skip the cache-drop — then the next read re-boots against the new
+        // state instead of serving a stale pack/config. `mutationRuntime` spreads
+        // `runtime`, so this is the same shared LazyStore. Only reached on the
+        // real-run branch (`confirm: true`); the plan-only preview never mutates.
+        runtime.store.invalidate();
+        await exec.dispose?.();
+      }
+    } catch (error) {
+      return toolError(asPragmaError(error));
+    }
+  };
+}
+
+/**
+ * Register one exposed verb as an MCP tool on the server.
+ *
+ * @param server - The MCP server to register onto.
+ * @param verb - The verb to expose (caller ensures `mcp.expose === true`).
+ * @param runtime - The runtime handed to the verb's `run`.
+ * @note Impure — mutates the server's tool registry.
+ */
+export function registerVerb(
+  server: McpServer,
+  verb: VerbSpec,
+  runtime: PragmaRuntime,
+): void {
+  const shape = buildZodSchema(verb.params);
+  // A verb with progressive disclosure gains a `detail` enum param derived from
+  // its DisclosureSpec (Risk2 — NO new VerbSpec field). The handler seeds
+  // globalFlags.detail from it per call, so MCP and CLI share one resolveDetail.
+  if (verb.disclosure) {
+    shape.detail = z
+      .enum(verb.disclosure.levels as unknown as [string, ...string[]])
+      .optional()
+      .describe(
+        `Progressive-disclosure level (${verb.disclosure.levels.join(", ")}); default ${verb.disclosure.default}.`,
+      );
+  }
+  if (verb.capability.mutates) {
+    shape.confirm = z
+      .boolean()
+      .default(false)
+      .describe("Set true to execute; otherwise a plan is returned.");
+    // Injected MCP-only per-call write root — added to the zod shape but NOT to
+    // verb.params (like `confirm`/`detail`), so `emitVerb` never emits it and the
+    // surface golden is untouched. The handler validates it and threads it as the
+    // single `rt.cwd` the jail + interpreter share (SEC-2 atomicity).
+    shape.cwd = z
+      .string()
+      .optional()
+      .describe(
+        "Absolute project directory to write into; defaults to the server's working directory.",
+      );
+  }
+
+  const config: {
+    description: string;
+    inputSchema?: z.ZodRawShape;
+    annotations: McpAnnotations;
+  } = {
+    // The agent-facing tool description is the verb's richer `doc` when present
+    // (pack `toolDescription`s compile into it; hand-written verbs author it
+    // directly), falling back to the one-line `summary`. Tool descriptions are
+    // NOT part of the frozen surface, so this stays covenant-safe.
+    description: verb.doc ?? verb.summary,
+    annotations: annotationsFor(verb),
+  };
+  if (Object.keys(shape).length > 0) config.inputSchema = shape;
+
+  const handler = verb.capability.mutates
+    ? mutateHandler(verb, runtime)
+    : readHandler(verb, runtime);
+
+  server.registerTool(
+    toolName(verb.path),
+    config,
+    handler as Parameters<McpServer["registerTool"]>[2],
+  );
+}

package/src/kernel/project/mcp/serve.ts

@@ -0,0 +1,34 @@
+/**
+ * Serve the MCP projector over stdio.
+ *
+ * The bin's `mcp` special-case (D9) and the hidden `mcp` meta verb both call
+ * this: build the server from the capabilities and connect it to a stdio
+ * transport. Kept separate from {@link buildServer} so tests can build a server
+ * without touching stdio.
+ */
+
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadEffectiveModules } from "../../packs/collect.js";
+import type { CapabilityModule } from "../../spec/types.js";
+import { buildServer } from "./buildServer.js";
+
+/**
+ * Build the MCP server and serve it over stdio until the transport closes.
+ *
+ * The server is a real invocation (not a fast path), so it merges config-declared
+ * story packs into the static capabilities before projecting the tool surface.
+ *
+ * @param modules - The static capability modules to project.
+ * @param cwd - The working directory for the server's runtime.
+ * @note Impure — reads config, connects to stdin/stdout.
+ */
+export async function serveMcp(
+  modules: readonly CapabilityModule[],
+  cwd?: string,
+): Promise<void> {
+  const dir = cwd ?? process.cwd();
+  const effective = await loadEffectiveModules(modules, dir);
+  const server = await buildServer(effective, dir);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}

package/src/kernel/project/mcp/toolDescriptions.test.ts

@@ -0,0 +1,80 @@
+/**
+ * MCP tool descriptions carry NO CLI-syntax leaks (a PR8 doc→MCP residue).
+ *
+ * A verb's `doc` doubles as its MCP tool description (`registerVerb`), so a doc
+ * authored in CLI terms leaks flags an agent can't use — `--all-tiers`,
+ * `--dry-run`/`--yes`, or a `pragma …` shell command — into the agent-facing
+ * catalog. Tool descriptions are NOT frozen in the covenant, so this is the guard
+ * against the leak (and its recurrence). Storeless: listing tools never boots the
+ * store, so no fixture graph is needed.
+ */
+
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { capabilities } from "../../../capabilities/index.js";
+import {
+  type McpHarness,
+  projectMcp,
+} from "../../../testing/helpers/projectMcp.js";
+
+let cwd: string;
+let mcp: McpHarness;
+let descriptions: { name: string; description: string }[];
+
+beforeAll(async () => {
+  cwd = mkdtempSync(join(tmpdir(), "pragma-tooldesc-"));
+  mcp = await projectMcp(capabilities, cwd);
+  const tools = await mcp.listTools();
+  descriptions = tools.map((tool) => ({
+    name: tool.name,
+    description: tool.description ?? "",
+  }));
+});
+
+afterAll(async () => {
+  await mcp.cleanup();
+  rmSync(cwd, { recursive: true, force: true });
+});
+
+describe("MCP tool descriptions — no CLI-syntax leaks (doc→MCP residue)", () => {
+  it("has a description for every registered tool", () => {
+    expect(descriptions.length).toBeGreaterThan(0);
+    for (const { name, description } of descriptions) {
+      expect(description.length, name).toBeGreaterThan(0);
+    }
+  });
+
+  it("no tool description embeds a CLI flag (`--flag`)", () => {
+    const leaks = descriptions.filter((tool) =>
+      /--[a-z]/.test(tool.description),
+    );
+    expect(leaks.map((tool) => `${tool.name}: ${tool.description}`)).toEqual(
+      [],
+    );
+  });
+
+  it("no tool description embeds a backtick-quoted `pragma …` command", () => {
+    const leaks = descriptions.filter((tool) =>
+      /`pragma /.test(tool.description),
+    );
+    expect(leaks.map((tool) => `${tool.name}: ${tool.description}`)).toEqual(
+      [],
+    );
+  });
+
+  it("the named leak sites are scrubbed but still substantive", () => {
+    const byName = new Map(
+      descriptions.map((tool) => [tool.name, tool.description]),
+    );
+    expect(byName.get("block_list")).not.toContain("--all-tiers");
+    expect(byName.get("graph_query")).not.toContain("pragma ontology list");
+    expect(byName.get("setup")).not.toMatch(/--dry-run|--yes/);
+    expect(byName.get("upgrade")).not.toContain("--dry-run");
+    // The scrub rephrases; it must not gut the description.
+    for (const tool of ["block_list", "graph_query", "setup", "upgrade"]) {
+      expect((byName.get(tool) ?? "").length, tool).toBeGreaterThan(20);
+    }
+  });
+});

package/src/kernel/render/__snapshots__/renderers.test.ts.snap

@@ -0,0 +1,127 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`error render matrix (× plain/llm/json) > renders each error across the three formats 1`] = `
+{
+  "empty": {
+    "json": "{"ok":false,"error":{"code":"EMPTY_RESULTS","message":"No tokens found.","validOptions":["stable","beta"],"filters":{"channel":"stable","tier":"core"}}}",
+    "llm": "## Error: EMPTY_RESULTS
+No tokens found.
+Filters: channel=stable, tier=core
+Valid options: stable, beta",
+    "plain": "Error: No tokens found.
+
+Active filters:
+  channel: stable
+  tier: core
+
+Valid options: stable, beta",
+  },
+  "notFound": {
+    "json": "{"ok":false,"error":{"code":"ENTITY_NOT_FOUND","message":"block \\"Buton\\" not found.","suggestions":["Button"],"recovery":{"message":"List available blocks.","cli":"pragma block list"}}}",
+    "llm": "## Error: ENTITY_NOT_FOUND
+block "Buton" not found.
+Suggestions: Button
+Recovery: List available blocks. \`pragma block list\`",
+    "plain": "Error: block "Buton" not found.
+
+Did you mean?
+  - Button
+
+List available blocks. Run \`pragma block list\`",
+  },
+}
+`;
+
+exports[`render matrix (list/lookup/empty × plain/llm/json × detail) > renders every scenario/format/detail combination 1`] = `
+{
+  "detailed": {
+    "empty": {
+      "json": "[]",
+      "llm": "## Widgets (0)
+",
+      "plain": "",
+    },
+    "list": {
+      "json": "[{"uri":"https://ds.canonical.com/Button","name":"Button","kind":"component","note":"Primary action"},{"uri":"https://ds.canonical.com/Card","name":"Card","kind":"pattern","note":""}]",
+      "llm": "## Widgets (2)
+
+- \`ds:Button\` — **Button** component | Primary action
+- \`ds:Card\` — **Card** pattern",
+      "plain": "ds:Button  Button  component  Primary action
+ds:Card    Card    pattern",
+    },
+    "lookup": {
+      "json": "{"uri":"https://ds.canonical.com/Button","name":"Button","kind":"component","note":"Primary action"}",
+      "llm": "## Button
+
+- Kind: component
+- URI: ds:Button
+
+### Note
+Primary action",
+      "plain": "Button
+════════════════════════
+
+  Kind: component
+  URI: ds:Button
+
+Note:
+  Primary action",
+    },
+  },
+  "standard": {
+    "empty": {
+      "json": "[]",
+      "llm": "## Widgets (0)
+",
+      "plain": "",
+    },
+    "list": {
+      "json": "[{"name":"Button","kind":"component"},{"name":"Card","kind":"pattern"}]",
+      "llm": "## Widgets (2)
+
+- **Button** component
+- **Card** pattern",
+      "plain": "Button  component
+Card    pattern",
+    },
+    "lookup": {
+      "json": "{"uri":"https://ds.canonical.com/Button","name":"Button","kind":"component","note":"Primary action"}",
+      "llm": "## Button
+
+- Kind: component",
+      "plain": "Button
+════════════════════════
+
+  Kind: component",
+    },
+  },
+  "summary": {
+    "empty": {
+      "json": "[]",
+      "llm": "## Widgets (0)
+",
+      "plain": "",
+    },
+    "list": {
+      "json": "[{"name":"Button"},{"name":"Card"}]",
+      "llm": "## Widgets (2)
+
+- **Button**
+- **Card**",
+      "plain": "Button
+Card",
+    },
+    "lookup": {
+      "json": "{"uri":"https://ds.canonical.com/Button","name":"Button","kind":"component","note":"Primary action"}",
+      "llm": "## Button
+
+- Kind: component",
+      "plain": "Button
+════════════════════════
+
+  Kind: component",
+    },
+  },
+}
+`;

package/src/kernel/render/compactUri.ts

@@ -0,0 +1,25 @@
+/**
+ * Compact a full URI to its prefixed form using the longest matching
+ * namespace. When two registered namespaces both prefix the URI (a base
+ * namespace and a sub-namespace), the longer — more specific — one wins.
+ * Falls back to the original URI when no namespace matches.
+ *
+ * @param fullUri - The absolute URI to compact.
+ * @param prefixes - A map of prefix to namespace IRI.
+ * @returns The `prefix:local` form, or `fullUri` unchanged when none matches.
+ */
+export function compactUri(
+  fullUri: string,
+  prefixes: Readonly<Record<string, string>>,
+): string {
+  let best: { prefix: string; namespace: string } | undefined;
+  for (const [prefix, namespace] of Object.entries(prefixes)) {
+    if (!fullUri.startsWith(namespace)) continue;
+    if (best === undefined || namespace.length > best.namespace.length) {
+      best = { prefix, namespace };
+    }
+  }
+
+  if (best === undefined) return fullUri;
+  return `${best.prefix}:${fullUri.slice(best.namespace.length)}`;
+}

package/src/kernel/render/contracts.ts

@@ -0,0 +1,72 @@
+/**
+ * Layout contracts for the generic list and lookup renderers.
+ *
+ * These describe *how* a domain's data is projected to text — which columns a
+ * list shows, which fields and sections a lookup renders — with no coupling to
+ * store shapes, filters, or effects. Domain formatters (PR2+) build these
+ * option bags and hand them to {@link renderers}.
+ */
+
+/** A single column in a list rendering. */
+export interface ColumnDef<T> {
+  readonly key: keyof T & string;
+  readonly label: string;
+  readonly format?: (value: unknown) => string;
+  readonly showWhenEmpty?: boolean;
+}
+
+/** The kinds of section a lookup can render. */
+export type SectionKind =
+  | "field"
+  | "code"
+  | "list"
+  | "table"
+  | "nested-table"
+  | "tree";
+
+/** A single section in a lookup rendering. */
+export interface SectionDef<T> {
+  readonly key: keyof T & string;
+  readonly heading: string;
+  readonly kind: SectionKind;
+  readonly showWhenEmpty?: boolean;
+}
+
+/** A single inline field rendered in a lookup heading block. */
+export interface LookupField<T> {
+  readonly label: string;
+  readonly value: (entity: T) => unknown;
+}
+
+/** Per-mode override callbacks for a lookup section. */
+export interface LookupSectionOverride<T> {
+  readonly plain?: (entity: T, section: SectionDef<T>) => string | null;
+  readonly llm?: (entity: T, section: SectionDef<T>) => string | null;
+}
+
+/** Options controlling the generic list renderer. */
+export interface RenderListOptions<T> {
+  readonly heading: string;
+  readonly columns: readonly ColumnDef<T>[];
+  readonly prefixes?: Readonly<Record<string, string>>;
+  /**
+   * The message shown when the list is empty, so zero results read as a calm,
+   * non-blank success (exit 0) rather than an empty screen. Omit to keep the
+   * bare-empty behavior (plain renders "", llm renders the `(0)` heading only).
+   */
+  readonly emptyMessage?: string;
+  /** An optional second line under {@link emptyMessage} — how to get results. */
+  readonly emptyHint?: string;
+}
+
+/** Options controlling the generic lookup renderer. */
+export interface RenderLookupOptions<T> {
+  readonly title: (entity: T) => string;
+  readonly fields: readonly LookupField<T>[];
+  readonly sections: readonly SectionDef<T>[];
+  readonly prefixes?: Readonly<Record<string, string>>;
+  readonly sectionOverrides?: Partial<
+    Record<keyof T & string, LookupSectionOverride<T>>
+  >;
+  readonly codeLanguage?: (section: SectionDef<T>, value: unknown) => string;
+}

package/src/kernel/render/disclosure.ts

@@ -0,0 +1,44 @@
+/**
+ * Progressive-disclosure resolution.
+ *
+ * A verb renders at one of {@link DETAIL_LEVELS}. The effective level is chosen
+ * from four sources, most specific first: the `--detail` flag, the resolved
+ * config's `detail`, the verb's own `disclosure.default`, and finally the
+ * built-in `"standard"`. Unknown values (a stale config, a typo) fall back to
+ * the default rather than erroring, so output never fails on disclosure.
+ */
+
+import {
+  DEFAULT_DETAIL_LEVEL,
+  DETAIL_LEVELS,
+  type DetailLevel,
+} from "../../constants.js";
+
+export { DETAIL_LEVELS };
+
+/** Type guard: is a string one of the recognized detail levels? */
+function isDetailLevel(value: string): value is DetailLevel {
+  return (DETAIL_LEVELS as readonly string[]).includes(value);
+}
+
+/**
+ * Resolve the effective disclosure level from its ordered sources.
+ *
+ * @param sources - Candidate levels, applied most-specific first.
+ * @param sources.flag - The explicit `--detail` value, if any.
+ * @param sources.config - The resolved config's `detail`, if any.
+ * @param sources.specDefault - The verb's `disclosure.default`, if any.
+ * @returns The first recognized level, or `"standard"` when none matches.
+ */
+export function resolveDetail(sources: {
+  flag?: string | undefined;
+  config?: string | undefined;
+  specDefault?: string | undefined;
+}): DetailLevel {
+  const candidate =
+    sources.flag ??
+    sources.config ??
+    sources.specDefault ??
+    DEFAULT_DETAIL_LEVEL;
+  return isDetailLevel(candidate) ? candidate : DEFAULT_DETAIL_LEVEL;
+}