@canonical/pragma-cli 0.31.0 → 0.33.0

package/src/capabilities/standard/parity.test.ts

@@ -0,0 +1,208 @@
+/**
+ * Standard-noun semantic parity (PROTECTED) — the bundled `standard` pack over a
+ * code-standards fixture graph.
+ *
+ * The hand-written standard domain is gone, so parity is asserted directly
+ * against the graph: every standard is reachable through list/lookup/categories/
+ * sample with the same names and values, addressable by name, prefixed name, and
+ * IRI, with the canonical disclosure levels (summary → base, `standard` → dos,
+ * `detailed` → dos + donts). `cs:extends` stays the raw IRI in data.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { compilePack } from "../../kernel/packs/compile.js";
+import type { LookupOutput } from "../../kernel/packs/resolveEntity.js";
+import { parsePackDefinition } from "../../kernel/packs/schema.js";
+import type { PackRow } from "../../kernel/packs/types.js";
+import { verbKey } from "../../kernel/packs/uniqueness.js";
+import { DEFAULT_PREFIX_MAP } from "../../kernel/render/prefixes.js";
+import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import { buildFixtureRuntime } from "../../testing/helpers/packRuntime.js";
+import { standardPack } from "./pack.js";
+
+const CS = "http://pragma.canonical.com/codestandards#";
+const PREFIXES = {
+  cs: CS,
+  owl: "http://www.w3.org/2002/07/owl#",
+  rdfs: "http://www.w3.org/2000/01/rdf-schema#",
+  xsd: "http://www.w3.org/2001/XMLSchema#",
+};
+
+const TTL = `
+@prefix cs: <${CS}> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+cs:CodeStandard a owl:Class .
+cs:Category a owl:Class .
+cs:Example a owl:Class .
+cs:name a owl:DatatypeProperty ; rdfs:domain cs:CodeStandard ; rdfs:range xsd:string .
+cs:description a owl:DatatypeProperty ; rdfs:range xsd:string .
+cs:hasCategory a owl:ObjectProperty ; rdfs:domain cs:CodeStandard ; rdfs:range cs:Category .
+cs:slug a owl:DatatypeProperty ; rdfs:domain cs:Category ; rdfs:range xsd:string .
+cs:extends a owl:ObjectProperty ; rdfs:domain cs:CodeStandard ; rdfs:range cs:CodeStandard .
+cs:do a owl:ObjectProperty ; rdfs:domain cs:CodeStandard ; rdfs:range cs:Example .
+cs:dont a owl:ObjectProperty ; rdfs:domain cs:CodeStandard ; rdfs:range cs:Example .
+cs:language a owl:DatatypeProperty ; rdfs:domain cs:Example ; rdfs:range xsd:string .
+cs:code a owl:DatatypeProperty ; rdfs:domain cs:Example ; rdfs:range xsd:string .
+
+cs:cat.react a cs:Category ; cs:slug "react" .
+cs:cat.code a cs:Category ; cs:slug "code" .
+
+cs:react.component.props a cs:CodeStandard ;
+  cs:name "react/component/props" ;
+  cs:description "Type component props explicitly." ;
+  cs:hasCategory cs:cat.react ;
+  cs:do [ a cs:Example ; cs:description "Do type props" ; cs:language "tsx" ; cs:code "interface P {}" ] ;
+  cs:dont [ a cs:Example ; cs:description "Avoid any" ; cs:language "tsx" ; cs:code "props: any" ] .
+
+cs:react.component.structure a cs:CodeStandard ;
+  cs:name "react/component/structure" ;
+  cs:description "Keep folder structure flat." ;
+  cs:hasCategory cs:cat.react ;
+  cs:extends cs:react.component.props ;
+  cs:do [ a cs:Example ; cs:description "Do flatten" ; cs:language "text" ; cs:code "src/Button.tsx" ] .
+
+cs:code.function.purity a cs:CodeStandard ;
+  cs:name "code/function/purity" ;
+  cs:description "Prefer pure functions." ;
+  cs:hasCategory cs:cat.code .
+`;
+
+const verbs = () =>
+  compilePack(standardPack, "bundled:standard", DEFAULT_PREFIX_MAP);
+const verb = (label: string) =>
+  verbs().find((v) => verbKey(v.path) === `standard ${label}`) as VerbSpec;
+
+let rt: PragmaRuntime;
+beforeAll(async () => {
+  ({ rt } = await buildFixtureRuntime({ ttl: TTL, prefixes: PREFIXES }));
+});
+afterAll(async () => {
+  (await rt.store.get()).store.dispose();
+});
+
+async function lookupAt(
+  name: string,
+  detail?: "summary" | "standard" | "detailed",
+): Promise<Record<string, unknown>> {
+  const runtime = detail
+    ? { ...rt, globalFlags: { ...rt.globalFlags, detail } }
+    : rt;
+  const out = (await verb("lookup").run(
+    { name: [name] },
+    runtime,
+  )) as LookupOutput;
+  return out.results.at(0) as Record<string, unknown>;
+}
+
+describe("standard pack definition (PROTECTED)", () => {
+  it("round-trips as declarative JSON and validates", () => {
+    expect(
+      parsePackDefinition(JSON.parse(JSON.stringify(standardPack)), "t"),
+    ).toEqual(standardPack);
+  });
+});
+
+describe("standard list parity", () => {
+  it("lists every standard with the uniform row shape", async () => {
+    const rows = (await verb("list").run({}, rt)) as PackRow[];
+    expect(rows.map((r) => r.name)).toEqual([
+      "code/function/purity",
+      "react/component/props",
+      "react/component/structure",
+    ]);
+    for (const row of rows) {
+      expect(row.uri).toBeTruthy();
+      expect(row.description).toBeTruthy();
+    }
+  });
+
+  it("filters by category and searches, conjunctively", async () => {
+    const react = (await verb("list").run(
+      { category: "react" },
+      rt,
+    )) as PackRow[];
+    expect(react.map((r) => r.name).sort()).toEqual([
+      "react/component/props",
+      "react/component/structure",
+    ]);
+    const searched = (await verb("list").run(
+      { category: "react", search: "structure" },
+      rt,
+    )) as PackRow[];
+    expect(searched.map((r) => r.name)).toEqual(["react/component/structure"]);
+  });
+});
+
+describe("standard categories parity", () => {
+  it("lists categories with their standard counts", async () => {
+    const rows = (await verb("categories").run({}, rt)) as PackRow[];
+    const counts = new Map(rows.map((r) => [r.name, Number(r.count)]));
+    expect(counts.get("react")).toBe(2);
+    expect(counts.get("code")).toBe(1);
+  });
+});
+
+describe("standard lookup parity — canonical disclosure", () => {
+  it("summary resolves base fields, no dos/donts", async () => {
+    const entity = await lookupAt("react/component/props", "summary");
+    expect(entity.name).toBe("react/component/props");
+    expect(entity.category).toBe("react");
+    expect(entity.description).toBe("Type component props explicitly.");
+    expect(entity.dos).toBeUndefined();
+    expect(entity.donts).toBeUndefined();
+  });
+
+  it("standard fetches dos; detailed fetches dos AND donts", async () => {
+    const atStandard = await lookupAt("react/component/props", "standard");
+    expect((atStandard.dos as unknown[]).length).toBeGreaterThan(0);
+    expect(atStandard.donts).toBeUndefined();
+
+    const atDetailed = await lookupAt("react/component/props", "detailed");
+    expect((atDetailed.dos as { code: string }[])[0]?.code).toBe(
+      "interface P {}",
+    );
+    expect((atDetailed.donts as { caption: string }[])[0]?.caption).toBe(
+      "Avoid any",
+    );
+  });
+
+  it("keeps cs:extends as the raw IRI in data", async () => {
+    const entity = await lookupAt("react/component/structure");
+    expect(entity.extends).toBe(`${CS}react.component.props`);
+  });
+
+  it("resolves the same entity by name and by prefixed name", async () => {
+    const byName = await lookupAt("react/component/props");
+    const byPrefixed = await lookupAt("cs:react.component.props");
+    expect(byPrefixed.name).toBe(byName.name);
+  });
+
+  it("expands globs and reports misses with suggestions", async () => {
+    const out = (await verb("lookup").run(
+      { name: ["react/component/*"] },
+      rt,
+    )) as LookupOutput;
+    expect(out.results.map((e) => e.name).sort()).toEqual([
+      "react/component/props",
+      "react/component/structure",
+    ]);
+    await expect(
+      verb("lookup").run({ name: ["react/component/prop"] }, rt),
+    ).rejects.toThrow(/not found/i);
+  });
+});
+
+describe("standard sample parity", () => {
+  it("returns N full exemplars with the population size", async () => {
+    const data = (await verb("sample").run({ count: "2" }, rt)) as {
+      samples: unknown[];
+      totalCount: number;
+    };
+    expect(data.samples).toHaveLength(2);
+    expect(data.totalCount).toBe(3);
+  });
+});

package/src/capabilities/surface.test.ts

@@ -0,0 +1,233 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { emitSurface } from "../kernel/spec/emitSurface.js";
+import {
+  assertConforms,
+  type Covenant,
+} from "../kernel/spec/surfaceConformance.js";
+import { capabilities } from "./index.js";
+
+/** The committed covenant, read from disk exactly as a consumer would. */
+const golden = JSON.parse(
+  readFileSync(
+    fileURLToPath(new URL("../../surface/surface.v2.json", import.meta.url)),
+    "utf-8",
+  ),
+) as Covenant;
+
+describe("surface conformance — capabilities ⊆ covenant (PROTECTED)", () => {
+  const emitted = emitSurface(capabilities);
+
+  it("the live capabilities conform to the frozen covenant", () => {
+    expect(() => assertConforms(emitted, golden)).not.toThrow();
+  });
+
+  it("emits config show + the one-command config set, in covenant order (field-verbs retired, B3)", () => {
+    // AV-228 B3 retired the per-field `tier`/`channel`/`detail` setters; the
+    // config noun is now just the `show` reader and the `set <key> <value>` writer.
+    expect(emitted.nouns.config?.verbs).toEqual([
+      { v: "show", mcp: "config_show" },
+      {
+        v: "set",
+        args: ["<key>", "<value>"],
+        mutates: true,
+        mcp: "config_set",
+      },
+    ]);
+    // info stays a data-only enrichment — its emitted verb is unchanged.
+    expect(emitted.nouns.info?.verbs).toEqual([{ v: "info", mcp: "info" }]);
+    // Hidden meta verbs (__complete, mcp) are excluded from the surface.
+    expect(emitted.nouns.mcp).toBeUndefined();
+    expect(emitted.nouns.__complete).toBeUndefined();
+  });
+
+  it("emits the read nouns/verbs the packs add (block list hand-written, sample only where declared)", () => {
+    expect(emitted.nouns.standard?.verbs.map((v) => v.v)).toEqual([
+      "list",
+      "categories",
+      "lookup",
+      "sample",
+    ]);
+    // PR7 completes the surface: tier gains a bespoke single-name lookup;
+    // block/modifier/token gain no-argument samples (fixedCount).
+    expect(emitted.nouns.tier?.verbs.map((v) => v.v)).toEqual([
+      "list",
+      "lookup",
+    ]);
+    expect(emitted.nouns.modifier?.verbs.map((v) => v.v)).toEqual([
+      "list",
+      "lookup",
+      "sample",
+    ]);
+    expect(emitted.nouns.token?.verbs.map((v) => v.v)).toEqual([
+      "list",
+      "lookup",
+      "sample",
+      "add-config",
+    ]);
+    expect(emitted.nouns.block?.verbs).toEqual([
+      {
+        v: "list",
+        flags: ["--all-tiers"],
+        needsStore: true,
+        mcp: "block_list",
+      },
+      {
+        v: "lookup",
+        args: ["<name...>"],
+        needsStore: true,
+        mcp: "block_lookup",
+      },
+      { v: "sample", needsStore: true, mcp: "block_sample" },
+    ]);
+    // The bespoke tier lookup emits the SINGLE-name positional the covenant
+    // freezes (a pack lookup would emit the variadic `<name...>`).
+    expect(emitted.nouns.tier?.verbs).toContainEqual({
+      v: "lookup",
+      args: ["<name>"],
+      needsStore: true,
+      mcp: "tier_lookup",
+    });
+  });
+
+  it("emits the authored read nouns (ontology TBox, storeless skill, graph inspect)", () => {
+    expect(emitted.nouns.ontology?.verbs).toEqual([
+      { v: "list", needsStore: true, mcp: "ontology_list" },
+      {
+        v: "lookup",
+        args: ["<prefix>"],
+        flags: ["--properties", "--full-uris", "--class"],
+        needsStore: true,
+        mcp: "ontology_lookup",
+      },
+      // `show` is the deprecated alias of `lookup` (AV-228 B1) — same shape,
+      // both blessed in the covenant.
+      {
+        v: "show",
+        args: ["<prefix>"],
+        flags: ["--properties", "--full-uris", "--class"],
+        needsStore: true,
+        mcp: "ontology_show",
+      },
+    ]);
+    // skill discovery is storeless (filesystem) — no needsStore.
+    expect(emitted.nouns.skill?.verbs).toEqual([
+      { v: "list", mcp: "skill_list" },
+      { v: "lookup", args: ["<name>"], mcp: "skill_lookup" },
+    ]);
+    // graph adds the SPARQL escape hatch (`query`) in PR6, alongside `inspect`.
+    expect(emitted.nouns.graph?.verbs).toEqual([
+      {
+        v: "inspect",
+        args: ["<uri>"],
+        needsStore: true,
+        mcp: "graph_inspect",
+      },
+      {
+        v: "query",
+        args: ["<sparql>"],
+        needsStore: true,
+        mcp: "graph_query",
+      },
+    ]);
+  });
+
+  it("emits the PR6 effect/diagnostic self-verbs (doctor, upgrade)", () => {
+    // doctor is a storeless read self-verb — no args, no flags, no needsStore.
+    expect(emitted.nouns.doctor?.verbs).toEqual([
+      { v: "doctor", mcp: "doctor" },
+    ]);
+    // upgrade is a storeless mutation self-verb — mutates, no args, no needsStore.
+    expect(emitted.nouns.upgrade?.verbs).toEqual([
+      { v: "upgrade", mutates: true, mcp: "upgrade" },
+    ]);
+  });
+
+  it("emits the PR10 colophon self-verb (storeless read)", () => {
+    // colophon is a storeless read self-verb — no args, no flags, no needsStore.
+    expect(emitted.nouns.colophon?.verbs).toEqual([
+      { v: "colophon", mcp: "colophon" },
+    ]);
+  });
+
+  it("emits setup as a mixed self+sub noun (self is a tool, sub-verbs are mcp:false)", () => {
+    // The one covenant noun both directly runnable AND with sub-verbs. The self
+    // verb is the `setup` tool; the four installers are CLI-only (mcp:false).
+    // The band-aware verbs (setup/mcp/skills) carry the --scope/--global/--local
+    // flags; completions/lsp are single-band installers with no scope.
+    expect(emitted.nouns.setup?.verbs).toEqual([
+      {
+        v: "setup",
+        flags: ["--scope", "--global", "--local"],
+        mutates: true,
+        mcp: "setup",
+      },
+      {
+        v: "mcp",
+        flags: ["--scope", "--global", "--local"],
+        mutates: true,
+        mcp: false,
+      },
+      { v: "completions", mutates: true, mcp: false },
+      {
+        v: "skills",
+        flags: ["--scope", "--global", "--local"],
+        mutates: true,
+        mcp: false,
+      },
+      { v: "lsp", mutates: true, mcp: false },
+    ]);
+  });
+
+  it("emits sorted tools, every one blessed by the covenant", () => {
+    const { tools } = emitted.mcpSurface;
+    expect(tools).toEqual([...tools].sort());
+    for (const tool of tools) {
+      expect(golden.mcpSurface.tools).toContain(tool);
+    }
+    // The ratified read tool names are load-bearing (lookup, NOT get).
+    for (const tool of [
+      "standard_lookup",
+      "block_lookup",
+      "modifier_lookup",
+      "token_lookup",
+      "standard_categories",
+      "standard_sample",
+      "tier_list",
+      "config_show",
+      "colophon",
+    ]) {
+      expect(tools).toContain(tool);
+    }
+  });
+});
+
+describe("surface COMPLETE — emitted == covenant (PROTECTED)", () => {
+  const emitted = emitSurface(capabilities);
+
+  // The CLOSING direction: assertConforms already proves emitted ⊆ covenant;
+  // this proves covenant ⊆ emitted, so together the tool sets are EQUAL — the
+  // surface-complete milestone. After PR7, every covenant tool is realized.
+  it("emits every covenant tool (all 38) — set equality with the covenant", () => {
+    const emittedTools = new Set(emitted.mcpSurface.tools);
+    const missing = golden.mcpSurface.tools.filter((t) => !emittedTools.has(t));
+    expect(missing).toEqual([]);
+    expect([...emitted.mcpSurface.tools].sort()).toEqual(
+      [...golden.mcpSurface.tools].sort(),
+    );
+    expect(emitted.mcpSurface.tools).toHaveLength(38);
+  });
+
+  // The covenant edit: the non-tool MCP surface is frozen too.
+  it("freezes the non-tool MCP surface (resources/prompts/instructions)", () => {
+    expect(emitted.mcpSurface.resources).toEqual(["pragma:{+uri}"]);
+    expect(emitted.mcpSurface.resources).toEqual(golden.mcpSurface.resources);
+    expect(emitted.mcpSurface.prompts).toBe(true);
+    expect(emitted.mcpSurface.prompts).toBe(golden.mcpSurface.prompts);
+    expect(emitted.mcpSurface.instructions).toBe(true);
+    expect(emitted.mcpSurface.instructions).toBe(
+      golden.mcpSurface.instructions,
+    );
+  });
+});

package/src/capabilities/tier/index.ts

@@ -0,0 +1,19 @@
+/**
+ * The `tier` capability module — the bundled flat-list pack compiled to `list`.
+ */
+
+import { compilePack } from "../../kernel/packs/compile.js";
+import { DEFAULT_PREFIX_MAP } from "../../kernel/render/prefixes.js";
+import type { CapabilityModule } from "../../kernel/spec/types.js";
+import { tierLookupVerb } from "./lookup.verb.js";
+import { tierPack } from "./pack.js";
+
+/** The `tier` capability module — the bundled flat-list pack plus the bespoke
+ * single-name `lookup` (a pack lookup would emit the variadic `<name...>`). */
+export const tierModule: CapabilityModule = {
+  name: "tier",
+  verbs: [
+    ...compilePack(tierPack, "bundled:tier", DEFAULT_PREFIX_MAP),
+    tierLookupVerb,
+  ],
+};

package/src/capabilities/tier/lookup.render.test.ts

@@ -0,0 +1,72 @@
+import chalk from "chalk";
+import { afterEach, describe, expect, it } from "vitest";
+import { type TierLookupData, tierLookupFormatters } from "./lookup.render.js";
+
+const TIER: TierLookupData = {
+  uri: "cs:apps/lxd-panel",
+  name: "apps/lxd-panel",
+  blocks: ["LXD Panel", "Status Bar"],
+};
+
+/** Run `body` with stdout's `isTTY` forced to `value`, then restore it. */
+function withStdoutTty(value: boolean | undefined, body: () => void): void {
+  const stream = process.stdout as { isTTY?: boolean };
+  const saved = stream.isTTY;
+  stream.isTTY = value;
+  try {
+    body();
+  } finally {
+    stream.isTTY = saved;
+  }
+}
+
+describe("tierLookupFormatters", () => {
+  it("underlines the plain title with an ═ rule (B7)", () => {
+    const [title, rule, blank, blocks] = tierLookupFormatters
+      .plain(TIER)
+      .split("\n");
+    expect(title).toBe("apps/lxd-panel (cs:apps/lxd-panel)");
+    expect(rule).toBe("═".repeat(Math.max((title as string).length, 24)));
+    expect(blank).toBe("");
+    expect(blocks).toBe("  blocks: LXD Panel, Status Bar");
+  });
+
+  it("floors the plain rule at 24 columns for a short title", () => {
+    const out = tierLookupFormatters.plain({ ...TIER, uri: "x", name: "a" });
+    expect(out.split("\n").at(1)).toBe("═".repeat(24));
+  });
+
+  it("heads the llm entity read at H2, never H1 (B2)", () => {
+    const out = tierLookupFormatters.llm(TIER);
+    expect(out.startsWith("## apps/lxd-panel\n")).toBe(true);
+    expect(out).not.toMatch(/^# /m);
+  });
+});
+
+describe("tierLookupFormatters — shared style seam (B7)", () => {
+  const prevLevel = chalk.level;
+  afterEach(() => {
+    chalk.level = prevLevel;
+  });
+
+  it("styles the plain title on a color-capable TTY (single-sourced frame)", () => {
+    chalk.level = 1;
+    withStdoutTty(true, () => {
+      // Delegating to `renderLookupPlain` now carries the same TTY tint block and
+      // skill lookups get — previously the tier title stayed unstyled.
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: asserting the ESC byte is the point
+      expect(tierLookupFormatters.plain(TIER)).toMatch(/\x1b\[/);
+    });
+  });
+
+  it("keeps piped plain output byte-stable off a TTY", () => {
+    chalk.level = 3;
+    withStdoutTty(undefined, () => {
+      const out = tierLookupFormatters.plain(TIER);
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: asserting NO ESC byte survives
+      expect(out).not.toMatch(/\x1b\[/);
+      expect(out.split("\n").at(0)).toBe("apps/lxd-panel (cs:apps/lxd-panel)");
+      expect(out.split("\n").at(3)).toBe("  blocks: LXD Panel, Status Bar");
+    });
+  });
+});

package/src/capabilities/tier/lookup.render.ts

@@ -0,0 +1,59 @@
+/**
+ * Formatters + data shape for `tier lookup <name>`.
+ */
+
+import type { RenderLookupOptions } from "../../kernel/render/contracts.js";
+import { renderLookupPlain } from "../../kernel/render/renderers.js";
+import type { Formatters } from "../../kernel/spec/types.js";
+
+/** The looked-up tier: its IRI, name, and the blocks scoped directly to it. */
+export interface TierLookupData {
+  readonly uri: string;
+  readonly name: string;
+  readonly blocks: readonly string[];
+}
+
+/**
+ * The shared plain-lookup layout for a tier: a `name (uri)` title over an ═ rule,
+ * then the directly-scoped blocks as one inline field. Delegating to
+ * {@link renderLookupPlain} single-sources the frame AND the TTY styling (bold
+ * title, dim rule, cyan label) that block/skill lookups already earn — so a tier
+ * title no longer stays unstyled on a terminal while theirs are bold (B7).
+ */
+const tierPlainOptions: RenderLookupOptions<TierLookupData> = {
+  title: (tier) => `${tier.name} (${tier.uri})`,
+  fields: [
+    {
+      label: "blocks",
+      // Pre-joined so the empty case still renders (the shared field renderer
+      // skips an empty array). Blocks are `ds:name` display strings, never IRIs,
+      // so the shared renderer's URI compaction is a no-op here — byte-stable.
+      value: (tier) =>
+        tier.blocks.length > 0
+          ? tier.blocks.join(", ")
+          : "(none scoped directly to this tier)",
+    },
+  ],
+  sections: [],
+};
+
+export const tierLookupFormatters: Formatters<TierLookupData> = {
+  plain(data) {
+    return renderLookupPlain(data, tierPlainOptions);
+  },
+  llm(data) {
+    // A byte-frozen agent contract that DIVERGES from the generic
+    // `renderLookupLlm`: an H2 `name` title (not `name (uri)`) with the IRI and
+    // blocks backtick-wrapped (`\`cs:…\``) — a shape the shared renderer does not
+    // emit. The llm path is never styled, so it has no TTY drift to single-source;
+    // kept inline so the frozen bytes hold (B2).
+    const lines = [`## ${data.name}`, `- IRI: \`${data.uri}\``];
+    if (data.blocks.length > 0) {
+      lines.push(`- Blocks: ${data.blocks.map((b) => `\`${b}\``).join(", ")}`);
+    }
+    return lines.join("\n");
+  },
+  json(data) {
+    return JSON.stringify(data);
+  },
+};

package/src/capabilities/tier/lookup.test.ts

@@ -0,0 +1,83 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import { CANONICAL_TTL } from "../../testing/fixtures/graph/canonical.js";
+import {
+  bootFixtureRuntime,
+  type FixtureGraph,
+} from "../../testing/helpers/fixtureGraph.js";
+import type { McpHarness } from "../../testing/helpers/projectMcp.js";
+import { projectMcp } from "../../testing/helpers/projectMcp.js";
+import { capabilities } from "../index.js";
+import { runTierLookup } from "./runLookup.js";
+
+let fixture: FixtureGraph;
+let mcp: McpHarness;
+
+beforeAll(async () => {
+  fixture = await bootFixtureRuntime({ ttl: CANONICAL_TTL });
+  mcp = await projectMcp(capabilities, fixture.cwd);
+});
+
+afterAll(async () => {
+  await mcp.cleanup();
+  await fixture.dispose();
+});
+
+describe("tier_lookup — bespoke single-name lookup (PROTECTED)", () => {
+  it("resolves a tier and the blocks scoped directly to it", async () => {
+    const result = await mcp.callTool("tier_lookup", { name: "apps/lxd" });
+    expect(result.ok).toBe(true);
+    const data = result.data as { name: string; blocks: string[] };
+    expect(data.name).toBe("apps/lxd");
+    // The canonical fixture scopes "LXD Panel" to apps/lxd.
+    expect(data.blocks).toContain("LXD Panel");
+  });
+
+  it("errors on an unknown tier name with a tier_list recovery", async () => {
+    const result = await mcp.callTool("tier_lookup", { name: "not-a-tier" });
+    expect(result.ok).toBe(false);
+    const error = result.error as { code: string };
+    expect(error.code).toBe("ENTITY_NOT_FOUND");
+  });
+
+  it("suggests a near-miss tier name from the full list (did-you-mean parity)", async () => {
+    // B6: tier lookup was the only entity lookup that omitted suggestions,
+    // though — like the others — it can read the full tier list on a miss.
+    let caught: unknown;
+    try {
+      await runTierLookup(fixture.runtime, "apps/lxdd");
+    } catch (error) {
+      caught = error;
+    }
+    expect(caught).toMatchObject({ code: "ENTITY_NOT_FOUND" });
+    expect((caught as { suggestions: string[] }).suggestions).toContain(
+      "apps/lxd",
+    );
+  });
+});
+
+describe("tier_lookup — cold/unseeded store (ROOT A)", () => {
+  it("remaps a 'Prefix not found' to STORE_UNAVAILABLE, not INTERNAL_ERROR", async () => {
+    // The bespoke lookup used to call `rt.query.sparql` directly, bypassing the
+    // `runSelect` remap — so a cold store's raw "Prefix not found" collapsed to
+    // INTERNAL_ERROR. It now routes through `runSelect`, inheriting the remap.
+    const coldRuntime = {
+      query: {
+        sparql: async () => {
+          throw new Error("Prefix not found: ds");
+        },
+      },
+    } as unknown as PragmaRuntime;
+
+    let caught: unknown;
+    try {
+      await runTierLookup(coldRuntime, "apps/lxd");
+    } catch (error) {
+      caught = error;
+    }
+    expect(caught).toMatchObject({ code: "STORE_UNAVAILABLE" });
+    expect(
+      (caught as { recovery?: { mcp?: { tool: string } } }).recovery?.mcp,
+    ).toMatchObject({ tool: "sources_update" });
+  });
+});