@canonical/pragma-cli 0.33.0 → 0.35.0

package/src/kernel/packs/graphqlSource.test.ts

@@ -17,6 +17,7 @@ import { buildLookupDocument } from "./graphql/buildLookupDocument.js";
 import type { LookupOutput } from "./resolveEntity.js";
 import { parsePackDefinition } from "./schema.js";
 import type { PackDefinition, PackLookup } from "./types.js";
+import { distributionSource } from "./types.js";
 import { verbKey } from "./uniqueness.js";
 
 const DS = "https://ds.canonical.com/";
@@ -292,9 +293,11 @@ describe("GraphQL lookup end to end + shape parity with SPARQL (PROTECTED)", ()
   });
 
   const lookupVia = (definition: PackDefinition, name: string) => {
-    const verb = compilePack(definition, "t", BLOCK_PREFIXES).find(
-      (v) => verbKey(v.path) === `${definition.noun} lookup`,
-    );
+    const verb = compilePack(
+      definition,
+      distributionSource("t"),
+      BLOCK_PREFIXES,
+    ).find((v) => verbKey(v.path) === `${definition.noun} lookup`);
     if (!verb) throw new Error("no lookup verb");
     return verb.run({ name: [name] }, rt) as Promise<LookupOutput>;
   };

package/src/kernel/packs/index.ts

@@ -0,0 +1,40 @@
+/**
+ * The packs domain — declared stories become runnable verbs.
+ *
+ * One pipeline runs end to end inside this folder: a JSON pack declaration is
+ * parsed and validated, compiled into `VerbSpec`s, and given run bodies that
+ * resolve entities out of the graph and formatters that render them. The
+ * intermediate stages — the schema parser, the query/render/run-body builders,
+ * the entity resolver, the sampler, the glob expander — are steps in that
+ * pipeline, not services, and they stay off this barrel: a caller reaching for
+ * one of them is a caller reassembling the pipeline by hand, and the whole
+ * point of compiling a pack once is that nobody has to.
+ *
+ * What crosses the boundary is the pipeline's ends and the contracts naming
+ * them. `compilePack` is the entry the distribution and the config-story path
+ * both take. `validateStories` and `loadEffectiveModules` are the two ways
+ * third-party stories are admitted — the first screens records and reports
+ * every problem (which is how `doctor` reports a story the CLI drops rather
+ * than letting it vanish), the second is the full load the MCP server and the
+ * `capabilities` verb take. `resolvePackDetail` and `resolveUri` are the two
+ * decisions a pack's own reads defer to the runtime, and `verbKey` is the
+ * identity function every surface keys a verb by.
+ *
+ * `loadEffectiveModules` reads config and the answering pack behind DYNAMIC
+ * imports so a bare `--help` never pays for either; consumers reach it lazily
+ * today for exactly that reason, and routing it through this barrel statically
+ * would put the config reader back on the fast path.
+ */
+
+export type { StoryProblem } from "./collect.js";
+export { loadEffectiveModules, validateStories } from "./collect.js";
+export { compilePack } from "./compile.js";
+export { resolvePackDetail } from "./disclosure.js";
+export { resolveUri } from "./iri.js";
+export type {
+  PackDefinition,
+  PackRow,
+  StorySource,
+} from "./types.js";
+export { distributionSource } from "./types.js";
+export { verbKey } from "./uniqueness.js";

package/src/kernel/packs/iri.test.ts

@@ -0,0 +1,73 @@
+/**
+ * URI resolution — what it accepts, and what it says when it refuses.
+ *
+ * Both halves matter and only one was covered. `resolveUri` is reached by every
+ * read (`graph inspect`, every pack lookup, the `pragma:{+uri}` resource), so
+ * its diagnostic is the sentence a user or an agent actually has to act on.
+ * Nothing asserted that sentence, which is how it came to quote a string the
+ * caller never typed.
+ */
+
+import { describe, expect, it } from "vitest";
+import { resolveUri } from "./iri.js";
+
+const DS = "https://ds.canonical.com/";
+const PREFIXES: Readonly<Record<string, string>> = { ds: DS };
+
+/** Run `resolveUri` and hand back whatever it threw, for assertion. */
+function refusal(uri: string): { code?: string; message?: string } {
+  try {
+    resolveUri(uri, PREFIXES);
+    throw new Error(`expected "${uri}" to be refused`);
+  } catch (error) {
+    return error as { code?: string; message?: string };
+  }
+}
+
+describe("resolveUri", () => {
+  it("resolves the plain forms", () => {
+    expect(resolveUri("ds:Component", PREFIXES)).toBe(`${DS}Component`);
+    expect(resolveUri(`${DS}Component`, PREFIXES)).toBe(`${DS}Component`);
+  });
+
+  it("accepts a percent-encoded prefixed name", () => {
+    // A client that encodes the URI it puts in a `pragma:{+uri}` read is not
+    // doing anything wrong; refusing it made the resource surface reject its
+    // own advertised identifiers.
+    expect(resolveUri("ds%3AComponent", PREFIXES)).toBe(`${DS}Component`);
+  });
+
+  it("names the URI the CALLER typed, not the expansion", () => {
+    // The safety check runs on the expanded IRI — it has to — but the message
+    // is for whoever typed the input, and they never typed the expansion.
+    const error = refusal("ds:my component");
+    expect(error.code).toBe("INVALID_INPUT");
+    expect(error.message).toContain("ds:my component");
+    expect(error.message).not.toContain(DS);
+  });
+
+  it("refuses malformed percent input as INVALID_INPUT, not a URIError", () => {
+    // `decodeURIComponent` throws `URIError` on a truncated escape. Escaping as
+    // a raw TypeError would surface as an internal fault rather than the
+    // caller's bad input.
+    const error = refusal("%E0%A4%A");
+    expect(error.code).toBe("INVALID_INPUT");
+    expect(error).not.toBeInstanceOf(URIError);
+    expect(error.message).toContain("%E0%A4%A");
+  });
+
+  it("refuses an unknown prefix and offers the ones it knows", () => {
+    const error = refusal("nope:Thing") as {
+      code?: string;
+      validOptions?: string[];
+    };
+    expect(error.code).toBe("INVALID_INPUT");
+    expect(error.validOptions).toContain("ds");
+  });
+
+  it("refuses a payload that would break out of the <iri> token", () => {
+    // The injection guard, asserted here rather than only through a verb.
+    const error = refusal('ds:x> } INSERT { ?s ?p "y" } #');
+    expect(error.code).toBe("INVALID_INPUT");
+  });
+});

package/src/kernel/packs/iri.ts

@@ -7,7 +7,7 @@
  * before it can be interpolated into a generated `<iri>` query token.
  */
 
-import { PragmaError } from "../error/PragmaError.js";
+import { cliRecovery, PragmaError } from "../error/index.js";
 
 /** Characters not allowed inside a SPARQL `<IRI>`. */
 const UNSAFE_IRI_PATTERN = /[<>"{}|\\^`\s]/;
@@ -26,6 +26,11 @@ export function isEmbeddableIri(value: string): boolean {
 /**
  * Resolve a prefixed or absolute URI to its full form.
  *
+ * A value that fails to resolve and carries a `%` is retried once decoded, so a
+ * client that percent-encodes the URI it addresses (`ds%3AComponent`) is served
+ * rather than rejected. Every diagnostic names the value the CALLER supplied —
+ * the safety check runs on the expansion, but nobody typed the expansion.
+ *
  * @param uri - A full or prefixed URI string.
  * @param prefixes - The store's merged prefix→namespace map.
  * @returns The fully expanded URI.
@@ -35,12 +40,35 @@ export function resolveUri(
   uri: string,
   prefixes: Readonly<Record<string, string>>,
 ): string {
+  const direct = tryResolveUri(uri, prefixes);
+  if (typeof direct === "string") return direct;
+
+  const decoded = uri.includes("%") ? decodeOnce(uri) : undefined;
+  if (decoded !== undefined && decoded !== uri) {
+    const viaDecoded = tryResolveUri(decoded, prefixes);
+    if (typeof viaDecoded === "string") return viaDecoded;
+  }
+
+  // Report the input as given, never the decoded or expanded form.
+  throw direct;
+}
+
+/**
+ * One resolution attempt: the expanded IRI, or the error describing `uri`.
+ *
+ * @param uri - The candidate URI, as the caller wrote it.
+ * @param prefixes - The store's merged prefix→namespace map.
+ * @returns The expanded IRI on success, else the PragmaError to report.
+ */
+function tryResolveUri(
+  uri: string,
+  prefixes: Readonly<Record<string, string>>,
+): string | PragmaError {
   const colonIdx = uri.indexOf(":");
   if (colonIdx === -1) {
-    throw PragmaError.invalidInput("uri", uri, {
+    return PragmaError.invalidInput("uri", uri, {
       recovery: {
-        message:
-          'Use a prefixed URI (e.g. "ds:global.component.button") or a full URI.',
+        message: 'Use a prefixed URI (e.g. "prefix:name") or a full URI.',
       },
     });
   }
@@ -49,30 +77,52 @@ export function resolveUri(
   const namespace = prefixes[prefix];
   if (namespace !== undefined) {
     const resolved = `${namespace}${uri.slice(colonIdx + 1)}`;
-    assertSafeIri(resolved);
-    return resolved;
+    return unsafeIriError(uri, resolved) ?? resolved;
   }
 
   if (ABSOLUTE_IRI_PATTERN.test(uri)) {
-    assertSafeIri(uri);
-    return uri;
+    return unsafeIriError(uri, uri) ?? uri;
   }
 
-  throw PragmaError.invalidInput("prefix", prefix, {
+  return PragmaError.invalidInput("prefix", prefix, {
     validOptions: Object.keys(prefixes),
-    recovery: {
-      message: "List known ontology prefixes.",
-      cli: "pragma ontology list",
-      mcp: { tool: "ontology_list" },
-    },
+    recovery: cliRecovery("ontology list", "List known ontology prefixes.", {
+      tool: "ontology_list",
+    }),
   });
 }
 
-/** @throws PragmaError INVALID_INPUT when the URI contains IRI-breaking characters. */
-function assertSafeIri(uri: string): void {
-  if (UNSAFE_IRI_PATTERN.test(uri)) {
-    throw PragmaError.invalidInput("uri", uri, {
-      recovery: { message: "URI contains characters not allowed in IRIs." },
-    });
+/**
+ * Guard the EXPANSION, name the INPUT: the check is on the IRI that would reach
+ * a query, the message is about the value the caller actually typed.
+ *
+ * @param input - The URI as the caller wrote it.
+ * @param resolved - The expanded IRI the check runs against.
+ * @returns The error when `resolved` carries IRI-breaking characters, else undefined.
+ */
+function unsafeIriError(
+  input: string,
+  resolved: string,
+): PragmaError | undefined {
+  if (!UNSAFE_IRI_PATTERN.test(resolved)) return undefined;
+  return PragmaError.invalidInput("uri", input, {
+    recovery: { message: "URI contains characters not allowed in IRIs." },
+  });
+}
+
+/**
+ * Percent-decode a value, tolerating malformed encodings.
+ *
+ * `decodeURIComponent` throws `URIError` on a stray `%` — a decode ATTEMPT must
+ * never turn a reportable input error into a crash.
+ *
+ * @param value - The possibly percent-encoded value.
+ * @returns The decoded value, or undefined when it cannot be decoded.
+ */
+function decodeOnce(value: string): string | undefined {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return undefined;
   }
 }

package/src/kernel/packs/renderPack.ts

@@ -9,20 +9,23 @@
  * them (disclosure gates the fetch), never HOW it is laid out.
  */
 
+import { BIN_NAME, RECOVERY_CLI_PREFIX } from "../../constants.js";
 import type {
   ColumnDef,
   LookupField,
   RenderListOptions,
   RenderLookupOptions,
   SectionDef,
-} from "../render/contracts.js";
+} from "../render/index.js";
+import { compactUri } from "../render/index.js";
 import {
+  renderListEmptyNotice,
   renderListLlm,
   renderListPlain,
   renderLookupLlm,
   renderLookupPlain,
 } from "../render/renderers.js";
-import type { Formatters } from "../spec/types.js";
+import type { Formatters } from "../spec/index.js";
 import type { LookupOutput } from "./resolveEntity.js";
 import type {
   PackChildRow,
@@ -52,8 +55,7 @@ export interface RenderMeta {
  * list on a BUILT store (a cold store would have failed with STORE_UNAVAILABLE
  * first) means "nothing matched", so point at both possible fixes.
  */
-const DEFAULT_EMPTY_HINT =
-  "If you haven't built the store yet, run `pragma sources update`; otherwise broaden your filter or channel.";
+const DEFAULT_EMPTY_HINT = `Build the store with \`${BIN_NAME} sources update\`, or broaden the filter or channel.`;
 
 /** Build the list formatters for a list-shaped verb (list or an extra verb). */
 export function listFormatters(
@@ -69,7 +71,9 @@ export function listFormatters(
   // `emptyRecovery` becomes the hint; otherwise the generic build/broaden hint.
   const emptyHint = shape.emptyRecovery
     ? `${shape.emptyRecovery.message}${
-        shape.emptyRecovery.cli ? ` Run \`${shape.emptyRecovery.cli}\`.` : ""
+        shape.emptyRecovery.cli
+          ? ` Run \`${RECOVERY_CLI_PREFIX}${shape.emptyRecovery.cli}\`.`
+          : ""
       }`
     : DEFAULT_EMPTY_HINT;
   const options: RenderListOptions<PackRow> = {
@@ -80,9 +84,13 @@ export function listFormatters(
     emptyHint,
   };
   return {
-    plain: (rows) => renderListPlain(rows, options),
+    plain: (rows, context) => renderListPlain(rows, options, context),
     llm: (rows) => renderListLlm(rows, options),
     json: (rows) => JSON.stringify(rows, null, 2),
+    // Zero rows: the dispatcher routes this to stderr (exit 0) so the plain
+    // stdout stream stays pure data; llm/json keep their own empty shapes.
+    emptyNotice: (rows) =>
+      rows.length === 0 ? renderListEmptyNotice(options) : undefined,
   };
 }
 
@@ -113,7 +121,11 @@ export function lookupOptions(
     }),
   );
   return {
-    title: (entity) => scalar(entity.name) ?? scalar(entity.uri) ?? "(unnamed)",
+    // An entity reached by IRI need not carry a `by` value, so the IRI is a
+    // real title, not a fallback nobody hits — and it is titled in the form the
+    // user addressed it with, not the expanded one they never typed.
+    title: (entity) =>
+      scalar(entity.name) ?? compactScalar(entity.uri, prefixes) ?? "(unnamed)",
     fields,
     sections: [...flatSections, ...expandSections],
     prefixes,
@@ -191,6 +203,15 @@ function scalar(
   return typeof value === "string" ? value : undefined;
 }
 
+/** A scalar URI in its prefixed display form, or undefined when it is neither. */
+function compactScalar(
+  value: string | readonly PackChildRow[] | undefined,
+  prefixes: Readonly<Record<string, string>>,
+): string | undefined {
+  const uri = scalar(value);
+  return uri === undefined ? undefined : compactUri(uri, prefixes);
+}
+
 function capitalize(value: string): string {
   return value.charAt(0).toUpperCase() + value.slice(1);
 }

package/src/kernel/packs/resolveEntity.test.ts

@@ -0,0 +1,213 @@
+/**
+ * Lookup ADDRESSING (PROTECTED): which argument shapes a pack lookup accepts,
+ * and whether the answer is the same twice.
+ *
+ * A lookup's `<name...>` positional is documented — in the generated reference,
+ * in the MCP tool schema, and by shell completion, which offers prefixed IRIs
+ * and nothing else — as accepting a name, a prefixed name, an absolute IRI, or
+ * a glob. These assert that the resolver honours the shape it is handed rather
+ * than the source its pack declares, that an entity is addressable by IRI even
+ * when it carries no `by` value, and that an ambiguous name resolves to the
+ * same entity on every store and every machine.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import {
+  AMBIGUOUS_TTL,
+  BLOCK_PREFIXES,
+  BLOCK_TTL,
+} from "../../testing/fixtures/blockGraph.js";
+import { buildFixtureRuntime } from "../../testing/helpers/packRuntime.js";
+import type { PragmaRuntime } from "../runtime/types.js";
+import { compilePack } from "./compile.js";
+import { lookupOptions } from "./renderPack.js";
+import type { LookupOutput } from "./resolveEntity.js";
+import type { PackDefinition, PackLookup } from "./types.js";
+import { distributionSource } from "./types.js";
+import { verbKey } from "./uniqueness.js";
+
+const DS = "https://ds.canonical.com/";
+
+/** A graphql-sourced pack — the shape `block` and `modifier` declare. */
+const GQL: PackDefinition = {
+  noun: "gblock",
+  lookup: {
+    source: "graphql",
+    by: "ds:name",
+    types: ["ds:Component", "ds:Pattern", "ds:Subcomponent"],
+    graphqlType: "UIBlock",
+    fields: [{ name: "summary", property: "ds:summary" }],
+  },
+};
+
+/** A sparql-sourced pack — the shape `tier`, `token` and `standard` declare. */
+const SPQ: PackDefinition = {
+  noun: "sblock",
+  lookup: {
+    source: "sparql",
+    by: "ds:name",
+    type: "ds:Component",
+    fields: [{ name: "summary", property: "ds:summary" }],
+  },
+};
+
+describe("pack lookup addressing (PROTECTED)", () => {
+  let rt: PragmaRuntime;
+
+  beforeAll(async () => {
+    ({ rt } = await buildFixtureRuntime({
+      ttl: BLOCK_TTL + AMBIGUOUS_TTL,
+      prefixes: BLOCK_PREFIXES,
+      detail: "detailed",
+    }));
+  });
+
+  afterAll(async () => {
+    (await rt.store.get()).store.dispose();
+  });
+
+  const lookupVia = (
+    definition: PackDefinition,
+    ...name: string[]
+  ): Promise<LookupOutput> => {
+    const verb = compilePack(
+      definition,
+      distributionSource("t"),
+      BLOCK_PREFIXES,
+    ).find((v) => verbKey(v.path) === `${definition.noun} lookup`);
+    if (!verb) throw new Error("no lookup verb");
+    return verb.run({ name }, rt) as Promise<LookupOutput>;
+  };
+
+  const uris = (out: LookupOutput): string[] =>
+    out.results.map((entity) => String(entity.uri));
+
+  describe("an IRI addresses an entity on EVERY pack, not just sparql ones", () => {
+    it("resolves a prefixed name on a graphql-sourced pack", async () => {
+      const out = await lookupVia(GQL, "ds:button");
+      expect(out.errors).toEqual([]);
+      expect(uris(out)).toEqual([`${DS}button`]);
+    });
+
+    it("resolves an absolute IRI on a graphql-sourced pack", async () => {
+      const out = await lookupVia(GQL, `${DS}modal`);
+      expect(out.errors).toEqual([]);
+      expect(uris(out)).toEqual([`${DS}modal`]);
+    });
+
+    it("still resolves a plain name on a graphql-sourced pack", async () => {
+      const out = await lookupVia(GQL, "Modal");
+      expect(uris(out)).toEqual([`${DS}modal`]);
+    });
+
+    it("reports an IRI that names nothing as a clean miss", async () => {
+      await expect(lookupVia(GQL, "ds:nosuchblock")).rejects.toMatchObject({
+        code: "ENTITY_NOT_FOUND",
+      });
+    });
+  });
+
+  describe("an IRI addresses an entity that carries no `by` value", () => {
+    it("resolves it on the sparql path", async () => {
+      const out = await lookupVia(SPQ, "ds:nameless.widget");
+      expect(out.errors).toEqual([]);
+      expect(uris(out)).toEqual([`${DS}nameless.widget`]);
+      expect(out.results.at(0)?.summary).toBe(
+        "Carries no ds:name; addressable only by IRI.",
+      );
+    });
+
+    it("resolves it on the graphql path", async () => {
+      const out = await lookupVia(GQL, "ds:nameless.widget");
+      expect(out.errors).toEqual([]);
+      expect(uris(out)).toEqual([`${DS}nameless.widget`]);
+    });
+
+    it("titles it with the prefixed IRI it was addressed by", () => {
+      const options = lookupOptions(SPQ.lookup as PackLookup, BLOCK_PREFIXES);
+      expect(options.title({ uri: `${DS}nameless.widget` })).toBe(
+        "ds:nameless.widget",
+      );
+    });
+  });
+
+  describe("a glob expands over the population its own shape addresses", () => {
+    it("expands an IRI-shaped glob on a sparql-sourced pack", async () => {
+      const out = await lookupVia(SPQ, "ds:*.chip");
+      expect(out.errors).toEqual([]);
+      expect(uris(out).sort()).toEqual([`${DS}alpha.chip`, `${DS}zeta.chip`]);
+    });
+
+    it("expands an IRI-shaped glob on a graphql-sourced pack", async () => {
+      const out = await lookupVia(GQL, "ds:button*");
+      expect(out.errors).toEqual([]);
+      expect(uris(out).sort()).toEqual([`${DS}button`, `${DS}button.icon`]);
+    });
+
+    it("reaches an entity with no `by` value through an IRI glob", async () => {
+      const out = await lookupVia(SPQ, "ds:nameless.*");
+      expect(uris(out)).toEqual([`${DS}nameless.widget`]);
+    });
+
+    it("still expands a name-shaped glob over names", async () => {
+      const out = await lookupVia(SPQ, "Mod*");
+      expect(uris(out)).toEqual([`${DS}modal`]);
+    });
+
+    it("expands an ABSOLUTE-IRI glob, not only the compact spelling", async () => {
+      // An entity under a registered prefix has two legal spellings, and a
+      // literal lookup honours both — so a glob that generalises one of them
+      // must too. Expanding over the compact form alone made
+      // `https://ds.canonical.com/but*` an EMPTY_RESULTS while the exact IRI
+      // it generalises resolved fine.
+      const out = await lookupVia(GQL, `${DS}button*`);
+      expect(out.errors).toEqual([]);
+      expect(uris(out).sort()).toEqual([`${DS}button`, `${DS}button.icon`]);
+    });
+
+    it("yields an entity ONCE when both its spellings match", async () => {
+      // Reachable, not defensive: a glob counts as IRI-shaped if it contains
+      // a colon, so `*:*chip` matches BOTH `ds:alpha.chip` and its absolute
+      // twin. That is why the population is a spelling→entity map rather than
+      // a flat list of both forms — a match under either spelling must render
+      // one row, not two.
+      const out = await lookupVia(SPQ, "*:*chip");
+      expect(uris(out).sort()).toEqual([`${DS}alpha.chip`, `${DS}zeta.chip`]);
+    });
+
+    it("reports an IRI-shaped glob that matches nothing", async () => {
+      await expect(lookupVia(SPQ, "ds:nosuch*")).rejects.toMatchObject({
+        code: "EMPTY_RESULTS",
+      });
+    });
+  });
+
+  describe("an ambiguous name resolves to the SAME entity every time", () => {
+    // `ds:zeta.chip` is declared BEFORE `ds:alpha.chip` in the fixture, so the
+    // store enumerates it first while IRI order puts `alpha` first. Without an
+    // explicit ORDER BY the winner is whichever the store happens to yield —
+    // exactly the cross-tier `Button` ambiguity in the live graph.
+    it("picks the lowest IRI on the sparql path", async () => {
+      const out = await lookupVia(SPQ, "Chip");
+      expect(uris(out)).toEqual([`${DS}alpha.chip`]);
+    });
+
+    it("picks the lowest IRI on the graphql path", async () => {
+      const out = await lookupVia(GQL, "Chip");
+      expect(uris(out)).toEqual([`${DS}alpha.chip`]);
+    });
+
+    it("agrees with itself across repeated resolves", async () => {
+      const runs = await Promise.all([
+        lookupVia(SPQ, "Chip"),
+        lookupVia(SPQ, "chip"),
+        lookupVia(GQL, "CHIP"),
+      ]);
+      expect(runs.map(uris)).toEqual([
+        [`${DS}alpha.chip`],
+        [`${DS}alpha.chip`],
+        [`${DS}alpha.chip`],
+      ]);
+    });
+  });
+});