@canonical/pragma-cli 0.27.1-experimental.0 → 0.30.0

package/src/domains/shared/stories/resolveLookupDetailed.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import resolveLookupDetailed from "./resolveLookupDetailed.js";
+import type { LookupStory } from "./types.js";
+
+type AnyLookupStory = LookupStory<unknown, unknown>;
+
+const baseStory: Pick<
+  AnyLookupStory,
+  "noun" | "description" | "toolDescription" | "namesDescription"
+> = {
+  noun: "thing",
+  description: "d",
+  toolDescription: "td",
+  namesDescription: "names",
+};
+
+function makeStory(overrides: Partial<AnyLookupStory>): AnyLookupStory {
+  return {
+    ...baseStory,
+    examples: [],
+    resolve: async () => ({ results: [], errors: [] }),
+    toFmtInput: (entity) => entity,
+    formatters: {
+      plain: () => "",
+      llm: () => "",
+      json: () => "",
+    },
+    ...overrides,
+  };
+}
+
+describe("resolveLookupDetailed", () => {
+  it("is never detailed when the story has no detailed param", () => {
+    const story = makeStory({});
+    expect(resolveLookupDetailed(story, "cli", { detailed: true })).toBe(false);
+    expect(resolveLookupDetailed(story, "mcp", {})).toBe(false);
+  });
+
+  it("defaults detailed to true on MCP and false on CLI", () => {
+    const story = makeStory({ detailedParam: { description: "d" } });
+    expect(resolveLookupDetailed(story, "mcp", {})).toBe(true);
+    expect(resolveLookupDetailed(story, "mcp", { detailed: false })).toBe(
+      false,
+    );
+    expect(resolveLookupDetailed(story, "cli", {})).toBe(false);
+    expect(resolveLookupDetailed(story, "cli", { detailed: true })).toBe(true);
+  });
+
+  it("lets a story override the surface defaults", () => {
+    const story = makeStory({
+      detailedParam: { description: "d" },
+      resolveDetailed: (surface) => surface === "cli",
+    });
+    expect(resolveLookupDetailed(story, "cli", {})).toBe(true);
+    expect(resolveLookupDetailed(story, "mcp", {})).toBe(false);
+  });
+});

package/src/domains/shared/stories/resolveLookupDetailed.ts

@@ -0,0 +1,27 @@
+import type { LookupStory } from "./types.js";
+
+/**
+ * Resolve the effective `detailed` flag for a lookup story on a surface.
+ *
+ * Defaults follow the ratified surface contract: the CLI opts in
+ * (`detailed` is false unless set) while MCP opts out (`detailed` is true
+ * unless set, since agents want full data by default). Stories without a
+ * `detailed` parameter are never detailed. A story's `resolveDetailed`
+ * override wins — block uses it to let aspect flags imply detail.
+ */
+export default function resolveLookupDetailed<TDetailed, TFmtInput>(
+  story: LookupStory<TDetailed, TFmtInput>,
+  surface: "cli" | "mcp",
+  params: Record<string, unknown>,
+): boolean {
+  if (story.resolveDetailed) {
+    return story.resolveDetailed(surface, params);
+  }
+  if (!story.detailedParam) {
+    return false;
+  }
+  if (surface === "mcp") {
+    return ((params.detailed as boolean | undefined) ?? true) === true;
+  }
+  return params.detailed === true;
+}

package/src/domains/shared/stories/types.ts

@@ -0,0 +1,171 @@
+/**
+ * Read-story spec types — one declaration per read story, many projections.
+ *
+ * A read story (list, show, or lookup) is declared once per domain and
+ * compiled into both surfaces: a cli-core `CommandDefinition` and a
+ * declarative MCP `ToolSpec`. The compilers in this folder own the shared
+ * execute skeletons — parameter projection, condensed rendering with token
+ * estimates, empty-result guards, and summary projection — so a domain
+ * supplies only its facts: descriptions, parameters, resolve function,
+ * formatters, and envelope mapping. This kills the per-domain duplication
+ * between `commands/*.ts` and `mcp/specs.ts` for read verbs and makes
+ * CLI/MCP parity structural instead of conventional.
+ */
+
+import type { CommandContext } from "@canonical/cli-core";
+import type { PragmaError } from "#error";
+import type { LookupResult } from "../contracts.js";
+import type { Formatters } from "../formatters.js";
+import type { PragmaRuntime } from "../types/index.js";
+
+/** Surfaces a story parameter is projected to (default: "both"). */
+export type StorySurface = "both" | "cli" | "mcp";
+
+/**
+ * Neutral parameter definition projected to a CLI flag and an MCP tool
+ * parameter. `string[]` becomes a CLI multiselect and an MCP string array.
+ */
+export interface StoryParam {
+  readonly name: string;
+  readonly type: "string" | "boolean" | "string[]";
+  /** CLI help text; also the MCP description unless `toolDescription` is set. */
+  readonly description: string;
+  /** MCP-specific description override. */
+  readonly toolDescription?: string;
+  readonly required?: boolean;
+  /** CLI default value — MCP parameters carry no defaults. */
+  readonly default?: unknown;
+  /** Allowed values; projects to CLI select choices and an MCP enum. */
+  readonly enum?: readonly string[];
+  /** If true, the CLI accepts this parameter as a positional argument. */
+  readonly positional?: boolean;
+  /** Surfaces this parameter appears on (default: "both"). */
+  readonly surfaces?: StorySurface;
+  /** CLI tab-completion for this parameter's argument. */
+  readonly complete?: (
+    partial: string,
+    ctx: CommandContext,
+  ) => Promise<string[]>;
+}
+
+/** MCP envelope fragment produced by a story's `toEnvelope`. */
+export interface StoryEnvelope {
+  readonly data: unknown;
+  readonly meta?: Record<string, unknown>;
+}
+
+/**
+ * A collection-or-singleton read story (`<noun> list`, `<noun> show`).
+ *
+ * `TData` is the domain's resolved payload; `TOutput` is the formatter and
+ * renderer input derived from it via `toOutput`.
+ */
+export interface ReadStory<TData, TOutput> {
+  readonly noun: string;
+  /** Read verb this story projects to (e.g. "list", "show"). */
+  readonly verb: string;
+  /** CLI one-line help description. */
+  readonly description: string;
+  /** MCP tool description. */
+  readonly toolDescription: string;
+  readonly params: readonly StoryParam[];
+  /** Usage examples shown in CLI help. */
+  readonly examples: readonly string[];
+  /** Fetch the story's data. Shared verbatim by both surfaces. */
+  readonly resolve: (
+    rt: PragmaRuntime,
+    params: Record<string, unknown>,
+  ) => Promise<TData>;
+  /** Map resolved data to the formatter/renderer input. */
+  readonly toOutput: (data: TData, params: Record<string, unknown>) => TOutput;
+  readonly formatters: Formatters<TOutput>;
+  /** Map resolved data to the MCP `{ data, meta }` envelope. */
+  readonly toEnvelope: (data: TData) => StoryEnvelope;
+  /**
+   * CLI-only pre-resolve guard: return an error to reject invalid
+   * parameters (e.g. an empty required positional).
+   */
+  readonly guardParams?: (
+    params: Record<string, unknown>,
+  ) => PragmaError | undefined;
+  /**
+   * CLI-only post-resolve guard: return an error to reject an empty
+   * result set with a recovery hint.
+   */
+  readonly emptyError?: (
+    data: TData,
+    params: Record<string, unknown>,
+  ) => PragmaError | undefined;
+  /** Optional interactive (ink) renderer for the CLI. */
+  readonly renderInk?: (output: TOutput) => unknown;
+}
+
+/** Per-invocation view state passed to lookup story hooks. */
+export interface LookupStoryView {
+  readonly surface: "cli" | "mcp";
+  /** Effective detail level after surface defaults and flag implications. */
+  readonly detailed: boolean;
+  readonly params: Record<string, unknown>;
+}
+
+/**
+ * A batch retrieval story (`<noun> lookup <names...>`).
+ *
+ * `TDetailed` is the looked-up entity; `TFmtInput` is the per-entity
+ * formatter input derived via `toFmtInput` (some domains pair the entity
+ * with view flags such as `detailed` or aspect selections).
+ */
+export interface LookupStory<TDetailed, TFmtInput> {
+  readonly noun: string;
+  readonly description: string;
+  readonly toolDescription: string;
+  /** CLI description of the `names` positional parameter. */
+  readonly namesDescription: string;
+  /** MCP-specific `names` description override. */
+  readonly namesToolDescription?: string;
+  /** CLI tab-completion for names. */
+  readonly complete?: (
+    partial: string,
+    ctx: CommandContext,
+  ) => Promise<string[]>;
+  /**
+   * The `detailed` toggle, when the story supports one. MCP defaults
+   * `detailed` to true; the CLI defaults it to false.
+   */
+  readonly detailedParam?: {
+    readonly description: string;
+    readonly toolDescription?: string;
+  };
+  /** Additional story parameters beyond `names` and `detailed`. */
+  readonly params?: readonly StoryParam[];
+  /** Named groups for organizing CLI parameters in help output. */
+  readonly parameterGroups?: Readonly<Record<string, readonly string[]>>;
+  readonly examples: readonly string[];
+  /** Resolve all queries, collecting per-query failures. */
+  readonly resolve: (
+    rt: PragmaRuntime,
+    names: readonly string[],
+    params: Record<string, unknown>,
+  ) => Promise<LookupResult<TDetailed>>;
+  /**
+   * Effective `detailed` for a surface. Defaults to the plain flag value
+   * (CLI: false unless set; MCP: true unless set). Domains override this
+   * when other flags imply detail (e.g. block aspect filters).
+   */
+  readonly resolveDetailed?: (
+    surface: "cli" | "mcp",
+    params: Record<string, unknown>,
+  ) => boolean;
+  /** Map an entity to the per-entity formatter input. */
+  readonly toFmtInput: (entity: TDetailed, view: LookupStoryView) => TFmtInput;
+  readonly formatters: Formatters<TFmtInput>;
+  /** MCP summary projection applied when `detailed` is false. */
+  readonly project?: (entity: TDetailed) => unknown;
+  /** CLI-only error thrown when no names are supplied. */
+  readonly emptyNamesError?: () => PragmaError;
+  /** Optional interactive (ink) renderer for the CLI. */
+  readonly renderInk?: (
+    result: LookupResult<TDetailed>,
+    view: LookupStoryView,
+  ) => unknown;
+}

package/src/domains/shared/suggestions/detectCrossDomain.test.ts

@@ -0,0 +1,43 @@
+import type { Store } from "@canonical/ke";
+import { describe, expect, it } from "vitest";
+import { createTestStore, DS_ALL_TTL } from "#testing";
+import detectCrossDomain from "./detectCrossDomain.js";
+
+let store: Store;
+let cleanup: () => void;
+
+describe("detectCrossDomain", () => {
+  beforeAll(async () => {
+    const result = await createTestStore({ ttl: DS_ALL_TTL });
+    store = result.store;
+    cleanup = result.cleanup;
+  });
+
+  afterAll(() => {
+    cleanup();
+  });
+
+  it("T2-4: returns undefined when name is not in any domain", async () => {
+    const hint = await detectCrossDomain("nonexistent_xyz", "token", store);
+    expect(hint).toBeUndefined();
+  });
+
+  it("returns a hint with the correct shape", async () => {
+    const hint = await detectCrossDomain("Button", "modifier", store);
+    if (hint) {
+      expect(hint).toHaveProperty("domain");
+      expect(hint).toHaveProperty("entityType");
+      expect(hint).toHaveProperty("cli");
+      expect(hint).toHaveProperty("mcp");
+      expect(hint.mcp).toHaveProperty("tool");
+      expect(hint.mcp).toHaveProperty("params");
+    }
+  });
+
+  it("skips the current domain", async () => {
+    const hint = await detectCrossDomain("Button", "block", store);
+    if (hint) {
+      expect(hint.domain).not.toBe("block");
+    }
+  });
+});

package/src/domains/shared/suggestions/detectCrossDomain.ts

@@ -0,0 +1,116 @@
+import type { SPARQL, Store } from "@canonical/ke";
+import { escapeSparqlValue } from "@canonical/ke";
+import { buildQuery } from "../buildQuery.js";
+import { P } from "../prefixes.js";
+
+/**
+ * Structured hint pointing the user/agent to the correct domain
+ * when a name exists in a different domain than the one queried.
+ */
+export interface CrossDomainHint {
+  /** Domain where the name was found (e.g., "modifier"). */
+  readonly domain: string;
+  /** Entity type label for messages (e.g., "modifier"). */
+  readonly entityType: string;
+  /** CLI recovery command. */
+  readonly cli: string;
+  /** MCP recovery tool + params. */
+  readonly mcp: { tool: string; params: Record<string, unknown> };
+}
+
+interface DomainSpec {
+  readonly domain: string;
+  readonly entityType: string;
+  readonly lookupTool: string;
+  readonly cliCommand: string;
+  readonly query: (name: string) => SPARQL<string>;
+}
+
+const DOMAIN_SPECS: readonly DomainSpec[] = [
+  {
+    domain: "block",
+    entityType: "block",
+    lookupTool: "block_lookup",
+    cliCommand: "pragma block lookup",
+    query: (name) =>
+      buildQuery(`
+        ASK {
+          VALUES ?type { ${P.ds}Component ${P.ds}Pattern ${P.ds}Layout ${P.ds}Subcomponent }
+          ?s a ?type ; ${P.ds}name ?name .
+          FILTER(LCASE(STR(?name)) = LCASE(${escapeSparqlValue(name)}))
+        }
+      `),
+  },
+  {
+    domain: "token",
+    entityType: "token",
+    lookupTool: "token_lookup",
+    cliCommand: "pragma token lookup",
+    query: (name) =>
+      buildQuery(`
+        ASK {
+          ?s a ${P.ds}Token ; ${P.ds}tokenId ?id .
+          FILTER(LCASE(STR(?id)) = LCASE(${escapeSparqlValue(name)}))
+        }
+      `),
+  },
+  {
+    domain: "modifier",
+    entityType: "modifier",
+    lookupTool: "modifier_lookup",
+    cliCommand: "pragma modifier lookup",
+    query: (name) =>
+      buildQuery(`
+        ASK {
+          ?s a ${P.ds}ModifierFamily ; ${P.ds}name ?name .
+          FILTER(LCASE(STR(?name)) = LCASE(${escapeSparqlValue(name)}))
+        }
+      `),
+  },
+  {
+    domain: "standard",
+    entityType: "standard",
+    lookupTool: "standard_lookup",
+    cliCommand: "pragma standard lookup",
+    query: (name) =>
+      buildQuery(`
+        ASK {
+          ?s a ${P.cs}CodeStandard ; ${P.cs}name ?name .
+          FILTER(LCASE(STR(?name)) = LCASE(${escapeSparqlValue(name)}))
+        }
+      `),
+  },
+];
+
+/**
+ * Check if a name exists in a domain other than the current one.
+ *
+ * Queries each domain in a deterministic order (block → token → modifier → standard)
+ * and returns the first match. Returns undefined if the name is not found anywhere.
+ *
+ * @param name - The user-supplied name.
+ * @param currentDomain - The domain the user queried (e.g., "token").
+ * @param store - ke store for cross-domain queries.
+ * @returns Hint pointing to the correct domain, or undefined.
+ */
+export default async function detectCrossDomain(
+  name: string,
+  currentDomain: string,
+  store: Store,
+): Promise<CrossDomainHint | undefined> {
+  for (const spec of DOMAIN_SPECS) {
+    if (spec.domain === currentDomain) continue;
+
+    const result = await store.query(spec.query(name));
+    if (result.type === "ask" && result.result) {
+      return {
+        domain: spec.domain,
+        entityType: spec.entityType,
+        cli: `${spec.cliCommand} ${name}`,
+        mcp: { tool: spec.lookupTool, params: { names: [name] } },
+      };
+    }
+  }
+
+  return undefined;
+}

package/src/domains/shared/suggestions/expandGlob.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from "vitest";
+import expandGlob, { isGlobPattern } from "./expandGlob.js";
+
+const standardNames = [
+  "react.component.props",
+  "react.component.structure.folder",
+  "react.component.barrel_exports",
+  "react.hooks.naming",
+  "css.selectors.namespace",
+  "css.selectors.specificity",
+  "css.component.encapsulation",
+  "git.branch.name",
+  "git.commit.message",
+];
+
+describe("expandGlob", () => {
+  it("T5-1: expands react.component.* to all matching entries", () => {
+    const result = expandGlob("react.component.*", standardNames);
+    expect(result).toContain("react.component.props");
+    expect(result).toContain("react.component.structure.folder");
+    expect(result).toContain("react.component.barrel_exports");
+    expect(result).not.toContain("react.hooks.naming");
+    expect(result).toHaveLength(3);
+  });
+
+  it("T5-2: expands css.* to all CSS entries", () => {
+    const result = expandGlob("css.*", standardNames);
+    expect(result).toHaveLength(3);
+    expect(result).toContain("css.selectors.namespace");
+  });
+
+  it("T5-3: expands prefix wildcard against plain names", () => {
+    const names = ["NavigationBar", "NavigationMenu", "Button"];
+    expect(expandGlob("Nav*", names)).toEqual([
+      "NavigationBar",
+      "NavigationMenu",
+    ]);
+  });
+
+  it("T5-4: full wildcard returns all candidates", () => {
+    expect(expandGlob("*", ["A", "B", "C"])).toEqual(["A", "B", "C"]);
+  });
+
+  it("T5-5: unmatched glob returns empty", () => {
+    expect(expandGlob("nonexistent.*", standardNames)).toEqual([]);
+  });
+
+  it("T5-6: non-glob name passes through unchanged", () => {
+    expect(expandGlob("Button", ["Button", "Card"])).toEqual(["Button"]);
+  });
+
+  it("T5-7: trailing dot treated as prefix glob", () => {
+    const withDot = expandGlob("react.component.", standardNames);
+    const withStar = expandGlob("react.component.*", standardNames);
+    expect(withDot).toEqual(withStar);
+  });
+
+  it("T5-8: suffix wildcard matches end of name", () => {
+    const result = expandGlob("*.props", [
+      "react.component.props",
+      "react.component.props.wrapper",
+      "css.selectors.namespace",
+    ]);
+    expect(result).toEqual(["react.component.props"]);
+  });
+
+  it("matches case-insensitively", () => {
+    expect(expandGlob("REACT.*", standardNames)).toHaveLength(4);
+  });
+});
+
+describe("isGlobPattern", () => {
+  it("T5-9: detects star pattern", () => {
+    expect(isGlobPattern("react.component.*")).toBe(true);
+  });
+
+  it("T5-10: detects prefix star", () => {
+    expect(isGlobPattern("Nav*")).toBe(true);
+  });
+
+  it("T5-11: detects trailing dot", () => {
+    expect(isGlobPattern("react.component.")).toBe(true);
+  });
+
+  it("T5-12: rejects plain name", () => {
+    expect(isGlobPattern("Button")).toBe(false);
+  });
+
+  it("T5-13: rejects empty string", () => {
+    expect(isGlobPattern("")).toBe(false);
+  });
+});

package/src/domains/shared/suggestions/expandGlob.ts

@@ -0,0 +1,52 @@
+/**
+ * Expand a glob pattern against a list of known names.
+ *
+ * Supports:
+ * - `*` anywhere: wildcard matching (`react.component.*`, `Nav*`, `*.props`)
+ * - Trailing `.`: shorthand for `.*` (`react.component.` = `react.component.*`)
+ *
+ * Non-glob names are returned unchanged (wrapped in a single-element array)
+ * so callers can pass the result directly to the lookup pipeline.
+ *
+ * @param pattern - User-supplied name, possibly containing glob characters.
+ * @param candidates - All known names in the domain.
+ * @returns Expanded concrete names, or empty array if no matches.
+ */
+export default function expandGlob(
+  pattern: string,
+  candidates: readonly string[],
+): string[] {
+  if (!isGlobPattern(pattern)) {
+    return [pattern];
+  }
+
+  const normalized = pattern.endsWith(".") ? `${pattern}*` : pattern;
+  const regex = globToRegex(normalized);
+
+  return candidates.filter((name) => regex.test(name));
+}
+
+/**
+ * Check whether a string contains glob meta-characters.
+ *
+ * A string is a glob pattern if it contains `*` or ends with `.` (trailing dot).
+ */
+export function isGlobPattern(name: string): boolean {
+  if (name === "") return false;
+  return name.includes("*") || name.endsWith(".");
+}
+
+function globToRegex(glob: string): RegExp {
+  let pattern = "";
+  for (const char of glob) {
+    if (char === "*") {
+      pattern += ".*";
+      // biome-ignore lint/suspicious/noTemplateCurlyInString: regex meta-characters to escape, not a JS template
+    } else if (".+^${}()|[]\\".includes(char)) {
+      pattern += `\\${char}`;
+    } else {
+      pattern += char;
+    }
+  }
+  return new RegExp(`^${pattern}$`, "i");
+}

package/src/domains/shared/suggestions/expandLookupQueries.ts

@@ -0,0 +1,57 @@
+import type { Store } from "@canonical/ke";
+import expandGlob, { isGlobPattern } from "./expandGlob.js";
+import type { Domain } from "./listDomainNames.js";
+import listDomainNames from "./listDomainNames.js";
+
+interface ExpandedQueries {
+  /** Concrete names to pass to lookupMany. */
+  readonly names: string[];
+  /** Errors for glob patterns that matched nothing. */
+  readonly globErrors: readonly {
+    query: string;
+    code: string;
+    message: string;
+  }[];
+}
+
+/**
+ * Partition lookup queries into concrete names and expanded globs.
+ *
+ * Literal names pass through unchanged. Glob patterns are expanded against
+ * the domain's full name list. Globs that match nothing produce an
+ * EMPTY_RESULTS error entry.
+ */
+export default async function expandLookupQueries(
+  queries: readonly string[],
+  store: Store,
+  domain: Domain,
+): Promise<ExpandedQueries> {
+  const hasGlobs = queries.some(isGlobPattern);
+  if (!hasGlobs) {
+    return { names: [...queries], globErrors: [] };
+  }
+
+  const allNames = await listDomainNames(store, domain);
+  const names: string[] = [];
+  const globErrors: { query: string; code: string; message: string }[] = [];
+
+  for (const query of queries) {
+    if (!isGlobPattern(query)) {
+      names.push(query);
+      continue;
+    }
+
+    const expanded = expandGlob(query, allNames);
+    if (expanded.length === 0) {
+      globErrors.push({
+        query,
+        code: "EMPTY_RESULTS",
+        message: `No ${domain}s matching "${query}".`,
+      });
+    } else {
+      names.push(...expanded);
+    }
+  }
+
+  return { names, globErrors };
+}

package/src/domains/shared/suggestions/index.ts

@@ -0,0 +1,7 @@
+export type { CrossDomainHint } from "./detectCrossDomain.js";
+export { default as detectCrossDomain } from "./detectCrossDomain.js";
+export { default as expandGlob, isGlobPattern } from "./expandGlob.js";
+export { default as expandLookupQueries } from "./expandLookupQueries.js";
+export type { Domain } from "./listDomainNames.js";
+export { default as listDomainNames } from "./listDomainNames.js";
+export { default as suggestNames } from "./suggestNames.js";

package/src/domains/shared/suggestions/listDomainNames.ts

@@ -0,0 +1,61 @@
+/**
+ * Lightweight name queries for each domain.
+ *
+ * Used by suggestNames to fetch candidate lists when a lookup fails.
+ * Each query returns only names (no detail) for minimal overhead.
+ */
+
+import type { SPARQL, Store } from "@canonical/ke";
+import { buildQuery } from "../buildQuery.js";
+import { P } from "../prefixes.js";
+
+type Domain = "block" | "token" | "modifier" | "standard" | "ontology";
+
+const QUERIES: Record<Domain, SPARQL<string>> = {
+  block: buildQuery(`
+    SELECT DISTINCT ?name WHERE {
+      VALUES ?type { ${P.ds}Component ${P.ds}Pattern ${P.ds}Layout ${P.ds}Subcomponent }
+      ?s a ?type ; ${P.ds}name ?name .
+    }
+  `),
+  token: buildQuery(`
+    SELECT DISTINCT ?name WHERE {
+      ?s a ${P.ds}Token ; ${P.ds}tokenId ?name .
+    }
+  `),
+  modifier: buildQuery(`
+    SELECT DISTINCT ?name WHERE {
+      ?s a ${P.ds}ModifierFamily ; ${P.ds}name ?name .
+    }
+  `),
+  standard: buildQuery(`
+    SELECT DISTINCT ?name WHERE {
+      ?s a ${P.cs}CodeStandard ; ${P.cs}name ?name .
+    }
+  `),
+  ontology: buildQuery(`
+    SELECT DISTINCT ?name WHERE {
+      ?s a owl:Ontology .
+      BIND(STR(?s) AS ?name)
+    }
+  `),
+};
+
+/**
+ * Fetch all entity names for a domain from the store.
+ *
+ * @note - This function is impure — it queries the ke store.
+ */
+export default async function listDomainNames(
+  store: Store,
+  domain: Domain,
+): Promise<string[]> {
+  const query = QUERIES[domain];
+  const result = await store.query(query);
+  if (result.type !== "select") return [];
+  return result.bindings
+    .map((b) => b.name)
+    .filter((n): n is string => typeof n === "string" && n !== "");
+}
+
+export type { Domain };