@canonical/pragma-cli 0.38.0 → 0.40.0

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

@@ -12,6 +12,7 @@ import { RECOVERY_CLI_PREFIX } from "../../constants.js";
 import { buildFixtureRuntime } from "../../testing/helpers/packRuntime.js";
 import { PragmaError } from "../error/index.js";
 import type { PragmaRuntime } from "../runtime/types.js";
+import { declareVerbs } from "../spec/call.js";
 import { kebabCase } from "../spec/emitSurface.js";
 import type { VerbSpec } from "../spec/types.js";
 import { compileListable, compilePack, compileStoryModule } from "./compile.js";
@@ -362,19 +363,28 @@ describe("the grammar rejects what the compiler cannot build (PROTECTED)", () =>
     );
   });
 
-  it("rejects an emptyRecovery.cli that names a binary, and names the change", () => {
-    // The hint is rendered as `<consuming distribution> <cli>`, so a story
-    // carrying the old prefixed form would render `pragma pragma sources
-    // update`. Third-party packs are third-party DATA: they get an error that
-    // names the grammar change, not a silently doubled string.
-    const withCli = (cli: string) => ({
+  it("rejects the retired emptyRecovery.cli and a call that is a command line, naming the change", () => {
+    // A recovery names a CALL — a verb path and a param bag — and the consuming
+    // distribution spells it per surface. Third-party packs are third-party
+    // DATA: the old `cli` string gets an error that names the grammar change,
+    // and a command line in `verb` would render `pragma pragma sources update`.
+    const withRecovery = (recovery: Record<string, unknown>) => ({
       noun: "widget",
-      list: { ...listShape, emptyRecovery: { message: "None.", cli } },
+      list: { ...listShape, emptyRecovery: { message: "None.", ...recovery } },
     });
-    expect(parse(withCli(`${RECOVERY_CLI_PREFIX}sources update`))).toThrow(
-      /WITHOUT the binary name/,
+    expect(parse(withRecovery({ cli: "sources update" }))).toThrow(
+      /emptyRecovery\.cli is now emptyRecovery\.call/,
     );
-    expect(parse(withCli("sources update"))).not.toThrow();
+    expect(
+      parse(
+        withRecovery({
+          call: { verb: `${RECOVERY_CLI_PREFIX}sources update` },
+        }),
+      ),
+    ).toThrow(/a call names a verb path/);
+    expect(
+      parse(withRecovery({ call: { verb: "sources update" } })),
+    ).not.toThrow();
   });
 });
 
@@ -387,6 +397,11 @@ describe("pack compiler — SPARQL fetch path (PROTECTED)", () => {
       prefixes: PREFIXES,
       detail: "detailed",
     }));
+    // A miss recovers to `widget list`; the suite checks every call it renders
+    // against the declared verbs, and a fixture's are not the distribution's.
+    declareVerbs(
+      compilePack(WIDGET_PACK, distributionSource("bundled:widget"), PREFIXES),
+    );
   });
 
   afterAll(async () => {
@@ -563,6 +578,88 @@ describe("pack compiler — SPARQL fetch path (PROTECTED)", () => {
  * once, for the name resolve, and the resource listing reads that same
  * declaration. Nothing to keep in sync because there is nothing written twice.
  */
+describe("a lookup that declares no disclosure can still be asked for less", () => {
+  /** The widget lookup with every trace of disclosure removed. */
+  const BARE_PACK: PackDefinition = {
+    noun: "widget",
+    lookup: {
+      source: "sparql",
+      by: "ex:name",
+      type: "ex:Widget",
+      fields: [{ name: "description", property: "ex:description" }],
+      expand: [
+        {
+          name: "parts",
+          relation: "ex:hasPart",
+          select: [{ name: "name", property: "ex:name" }],
+        },
+      ],
+    },
+  };
+  const lookupVerb = compilePack(
+    BARE_PACK,
+    distributionSource("bundled:widget"),
+    PREFIXES,
+  ).find((v) => verbKey(v.path) === "widget lookup") as VerbSpec;
+
+  const lookupAt = async (options: {
+    detail?: "summary" | "standard" | "detailed";
+    configDetail?: "summary";
+  }) => {
+    const { rt } = await buildFixtureRuntime({
+      ttl: TTL,
+      prefixes: PREFIXES,
+      ...(options.detail ? { detail: options.detail } : {}),
+      ...(options.configDetail
+        ? { configDetail: options.configDetail, detailOrigin: "project" }
+        : {}),
+    });
+    try {
+      const out = (await lookupVerb.run(
+        { name: ["Button"] },
+        rt,
+      )) as LookupOutput;
+      return out.results.at(0);
+    } finally {
+      (await rt.store.get()).store.dispose();
+    }
+  };
+
+  it("advertises the canonical levels, defaulting to the fullest", () => {
+    expect(lookupVerb.disclosure).toEqual({
+      levels: ["summary", "standard", "detailed"],
+      default: "detailed",
+    });
+  });
+
+  it("answers exactly as before when nothing is asked for", async () => {
+    expect(await lookupAt({})).toEqual(await lookupAt({ detail: "detailed" }));
+    expect((await lookupAt({}))?.parts).toEqual([{ name: "Label" }]);
+  });
+
+  it("is the fields alone at summary, and everything from standard", async () => {
+    const summary = await lookupAt({ detail: "summary" });
+    expect(summary).toMatchObject({ description: "A button." });
+    expect(summary).not.toHaveProperty("parts");
+    expect(await lookupAt({ detail: "standard" })).toHaveProperty("parts");
+  });
+
+  it("follows a configured detail, as a declared disclosure always did", async () => {
+    expect(await lookupAt({ configDetail: "summary" })).not.toHaveProperty(
+      "parts",
+    );
+  });
+
+  it("leaves a declared disclosure exactly as its author wrote it", () => {
+    const declared = compilePack(
+      WIDGET_PACK,
+      distributionSource("bundled:widget"),
+      PREFIXES,
+    ).find((v) => verbKey(v.path) === "widget lookup");
+    expect(declared?.disclosure?.default).toBe("summary");
+  });
+});
+
 describe("declared listing (derived from the lookup's types)", () => {
   it("derives one collection per declared type, unweighted types at 1", () => {
     expect(

package/src/kernel/packs/compile.ts

@@ -14,7 +14,7 @@
  * facade).
  */
 
-import { BIN_NAME } from "../../constants.js";
+import { BIN_NAME, DETAIL_LEVELS } from "../../constants.js";
 import { PragmaError } from "../error/index.js";
 import { compactUri, DEFAULT_PREFIX_MAP } from "../render/index.js";
 import type { PragmaRuntime } from "../runtime/index.js";
@@ -42,8 +42,10 @@ import {
 import { storyIssues } from "./storyRules.js";
 import {
   EVERY_TIER,
+  type NounLookups,
   type PackDefinition,
   type PackFilter,
+  type PackGuidance,
   type PackList,
   type PackLookup,
   type PackPage,
@@ -74,17 +76,22 @@ const READ_CAPABILITY = {
  * @param definition - A validated pack definition.
  * @param source - Where the definition came from, for diagnostics.
  * @param prefixes - The merged prefix map used for display compaction.
+ * @param nouns - The other stories' lookups, which a filter naming a noun
+ *   resolves its values through. Read at run time only.
  * @returns The compiled verbs (list, extra verbs, lookup, sample), in order.
  */
 export function compilePack(
   definition: PackDefinition,
   source: StorySource,
   prefixes: Readonly<Record<string, string>>,
+  nouns?: NounLookups,
 ): VerbSpec[] {
   const { noun } = definition;
   const verbs: VerbSpec[] = [];
 
   const tierScope = definition.tierScope;
+  // A story may declare a lookup alone; a miss must not point at a `list` it lacks.
+  const hasList = definition.list !== undefined;
 
   if (definition.list) {
     verbs.push(
@@ -93,8 +100,10 @@ export function compilePack(
         verb: "list",
         summary: definition.description ?? `List ${noun} entries.`,
         doc: definition.toolDescription,
+        ...guidanceOf(definition),
         source,
         prefixes,
+        ...(nouns ? { nouns } : {}),
         ...(tierScope ? { tierScope } : {}),
       }),
     );
@@ -107,19 +116,24 @@ export function compilePack(
         verb: verb.verb,
         summary: verb.description ?? `List ${noun} ${verb.verb}.`,
         doc: verb.toolDescription,
+        ...guidanceOf(verb),
         source,
         prefixes,
+        ...(nouns ? { nouns } : {}),
         ...(tierScope ? { tierScope } : {}),
       }),
     );
   }
 
   if (definition.lookup) {
+    // Normalised ONCE, here, so the lookup verb, its run body, both fetch lanes
+    // and the sample all read the same declaration.
+    const lookup = withDisclosure(definition.lookup);
     verbs.push(
-      compileLookupVerb(definition.lookup, noun, source, prefixes, tierScope),
+      compileLookupVerb(lookup, noun, source, prefixes, hasList, tierScope),
     );
-    if (definition.lookup.sample) {
-      verbs.push(compileSampleVerb(definition.lookup, noun, source, prefixes));
+    if (lookup.sample) {
+      verbs.push(compileSampleVerb(lookup, noun, source, prefixes, hasList));
     }
   }
 
@@ -195,6 +209,7 @@ export function compileListable(
  * @param definition - A validated pack definition.
  * @param source - Where the definition came from, for diagnostics.
  * @param prefixes - The merged prefix map used for display compaction.
+ * @param nouns - As {@link compilePack}.
  * @returns The module: the compiled verbs plus the story's module-level data.
  * @throws PragmaError CONFIG_ERROR when the definition cannot be compiled,
  *   naming the field and the rule.
@@ -203,6 +218,7 @@ export function compileStoryModule(
   definition: PackDefinition,
   source: StorySource,
   prefixes: Readonly<Record<string, string>>,
+  nouns?: NounLookups,
 ): CapabilityModule {
   const issue = storyIssues(definition)[0];
   if (issue) {
@@ -211,17 +227,47 @@ export function compileStoryModule(
     );
   }
   const listable = compileListable(definition);
-  return {
+  const module: CapabilityModule = {
     name: definition.noun,
     story: true,
-    verbs: compilePack(definition, source, prefixes),
+    verbs: compilePack(definition, source, prefixes, nouns),
     colophon: definition.colophon,
     ...(listable ? { mcpListable: listable } : {}),
   };
+  compiledFrom.set(module, { definition, source, prefixes });
+  return module;
+}
+
+/** What each story module was compiled from. */
+const compiledFrom = new WeakMap<
+  CapabilityModule,
+  {
+    readonly definition: PackDefinition;
+    readonly source: StorySource;
+    readonly prefixes: Readonly<Record<string, string>>;
+  }
+>();
+
+/**
+ * The story a module was compiled from by {@link compileStoryModule}, with the
+ * source and prefixes it was compiled under; `undefined` for any other module.
+ */
+export function storyOf(
+  module: CapabilityModule,
+): ReturnType<(typeof compiledFrom)["get"]> {
+  return compiledFrom.get(module);
+}
+
+/** Carry a story half's declared guidance onto its verb, omitting what is absent. */
+function guidanceOf(half: PackGuidance): Pick<VerbSpec, "useWhen" | "example"> {
+  return {
+    ...(half.useWhen ? { useWhen: half.useWhen } : {}),
+    ...(half.example ? { example: half.example } : {}),
+  };
 }
 
 /** Presentation facts for one compiled list-shaped verb. */
-interface ListVerbMeta {
+interface ListVerbMeta extends PackGuidance {
   readonly noun: string;
   readonly verb: string;
   readonly summary: string;
@@ -229,6 +275,8 @@ interface ListVerbMeta {
   readonly doc?: string;
   readonly source: StorySource;
   readonly prefixes: Readonly<Record<string, string>>;
+  /** The other stories' lookups, for a filter that names a noun. */
+  readonly nouns?: NounLookups;
   /** The noun's declared tier hierarchy, when its entities are tiered. */
   readonly tierScope?: PackTierScope;
 }
@@ -246,6 +294,7 @@ function compileListVerb(shape: PackList, meta: ListVerbMeta): VerbSpec {
     path: [meta.noun, meta.verb],
     summary: meta.summary,
     ...(meta.doc ? { doc: meta.doc } : {}),
+    ...guidanceOf(meta),
     params,
     output: {
       formatters: listFormatters(shape, {
@@ -272,6 +321,8 @@ function compileListVerb(shape: PackList, meta: ListVerbMeta): VerbSpec {
       runBodies().then((m) =>
         m.makeListRun(shape, {
           source: meta.source,
+          prefixes: meta.prefixes,
+          ...(meta.nouns ? { nouns: meta.nouns } : {}),
           ...(meta.tierScope ? { tierScope: meta.tierScope } : {}),
         })(params, rt),
       ),
@@ -285,6 +336,7 @@ function compileLookupVerb(
   noun: string,
   source: StorySource,
   prefixes: Readonly<Record<string, string>>,
+  hasList: boolean,
   tierScope?: PackTierScope,
 ): VerbSpec {
   // Derive-by-default: every lookup completes its `<name>` from the pack index
@@ -319,6 +371,7 @@ function compileLookupVerb(
     summary:
       lookup.description ?? `Look up ${noun} details by name, IRI, or glob.`,
     ...(lookup.toolDescription ? { doc: lookup.toolDescription } : {}),
+    ...guidanceOf(lookup),
     params: [nameParam, ...tierParams(tierScope)],
     output: { formatters: lookupFormatters(lookup, prefixes) },
     examples: [
@@ -332,13 +385,18 @@ function compileLookupVerb(
           ]
         : []),
     ],
-    ...(lookup.disclosure
-      ? { disclosure: disclosureSpec(lookup.disclosure) }
-      : {}),
+    disclosure: disclosureSpec(lookup.disclosure),
     capability: READ_CAPABILITY,
     run: (params: Record<string, unknown>, rt: PragmaRuntime) =>
       runBodies().then((m) =>
-        m.makeLookupRun(lookup, noun, source, prefixes, tierScope)(params, rt),
+        m.makeLookupRun(
+          lookup,
+          noun,
+          source,
+          prefixes,
+          hasList,
+          tierScope,
+        )(params, rt),
       ),
   };
   return asVerb(verb);
@@ -374,6 +432,7 @@ function compileSampleVerb(
   noun: string,
   source: StorySource,
   prefixes: Readonly<Record<string, string>>,
+  hasList: boolean,
 ): VerbSpec {
   const defaultCount = sampleDefaultCount(lookup);
   const config = lookup.sample === true ? undefined : lookup.sample;
@@ -396,6 +455,7 @@ function compileSampleVerb(
       config?.description ??
       `Return randomly selected complete ${noun} entries as exemplars.`,
     ...(config?.toolDescription ? { doc: config.toolDescription } : {}),
+    ...guidanceOf(config ?? {}),
     params: countParam,
     output: { formatters: sampleFormatters(lookup, noun, prefixes) },
     examples: [
@@ -411,12 +471,41 @@ function compileSampleVerb(
           source,
           prefixes,
           defaultCount,
+          hasList,
         )(params, rt),
       ),
   };
   return asVerb(verb);
 }
 
+/**
+ * Give a lookup that declares no disclosure the canonical ladder: default
+ * `detailed` (so its default answer is unchanged) and untagged expands from
+ * `standard` (so `summary` is the fields alone, and `standard` equals
+ * `detailed`). A declared disclosure is returned as written.
+ */
+function withDisclosure(lookup: PackLookup): PackLookup {
+  if (lookup.disclosure) return lookup;
+  return {
+    ...lookup,
+    disclosure: { levels: [...DETAIL_LEVELS], default: IMPUTED_DEFAULT_LEVEL },
+    ...(lookup.expand
+      ? {
+          expand: lookup.expand.map((expand) => ({
+            ...expand,
+            level: expand.level ?? IMPUTED_EXPAND_LEVEL,
+          })),
+        }
+      : {}),
+  };
+}
+
+/** The level an imputed disclosure answers at when none is asked for: all of it. */
+const IMPUTED_DEFAULT_LEVEL = "detailed";
+
+/** The level from which an imputed disclosure shows an untagged expand. */
+const IMPUTED_EXPAND_LEVEL = "standard";
+
 /** Normalize a pack disclosure into a {@link DisclosureSpec} (default → base). */
 function disclosureSpec(disclosure: PackLookup["disclosure"]): DisclosureSpec {
   const levels = disclosure?.levels ?? [];

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

@@ -58,7 +58,7 @@ ex:slider a ex:Widget ; ex:name "Slider" ; ex:kind "input" .
 const EMPTY_RECOVERY = {
   message:
     "Widgets are recorded by the catalogue build, and a store built before it ran records none.",
-  cli: "sources update",
+  call: { verb: "sources update" },
 } as const;
 
 const listShape = (uriClass: string) => ({
@@ -133,10 +133,12 @@ describe("a zero-row answer names the filter and keeps the recovery", () => {
     expect(outcome.exitCode).toBe(0);
     const said = `${outcome.stdout ?? ""}${outcome.stderr ?? ""}`;
     expect(said).toContain("No widget matches `--search zzzznotreal`.");
-    // The filter is the news; the story's account of where widgets come from is
-    // the other half, and a reader who mistyped nothing needs it.
+    // The filter is the news, with how to widen; the story's account of where
+    // widgets come from is kept — and the rebuild is not advised, because a
+    // filter that missed says nothing about the store.
+    expect(said).toContain("drop the argument, or loosen it");
     expect(said).toContain("recorded by the catalogue build");
-    expect(said).toContain("pragma sources update");
+    expect(said).not.toContain("sources update");
   });
 
   it("every filter in force is named", async () => {
@@ -195,7 +197,7 @@ describe("a zero-row answer names the filter and keeps the recovery", () => {
     const said = `${outcome.stderr ?? ""}`;
     expect(said).toContain("No gadget matches `--kind input`.");
     expect(said).toContain("recorded by the catalogue build");
-    expect(said).toContain("pragma sources update");
+    expect(said).not.toContain("sources update");
   });
 
   it("an EMPTY POPULATION unfiltered gets the kernel's own sentence", async () => {
@@ -210,4 +212,19 @@ describe("a zero-row answer names the filter and keeps the recovery", () => {
     expect(outcome.stderr).toContain("recorded by the catalogue build");
     expect(outcome.stderr).toContain("pragma sources update");
   });
+
+  it("a story with no recovery of its own: rebuild unfiltered, never when filtered", async () => {
+    const bare: PackDefinition = {
+      ...GADGET_PACK,
+      list: { ...listShape("ex:Gadget") },
+    };
+    const said = async (params: Record<string, unknown>): Promise<string> =>
+      (await executeVerb(listVerb(bare), params, REAL, as(PLAIN))).stderr ?? "";
+
+    expect(await said({})).toContain("pragma sources update");
+    const filtered = await said({ kind: "input" });
+    expect(filtered).toContain("drop the argument, or loosen it");
+    expect(filtered).not.toContain("sources update");
+    expect(filtered).not.toContain("needs building");
+  });
 });

package/src/kernel/packs/graphql/fetchGraphqlLookup.ts

@@ -14,7 +14,7 @@
  * composed only from validated pack terms and compiled schema names.
  */
 
-import { cliRecovery, PragmaError } from "../../error/index.js";
+import { callRecovery, PragmaError } from "../../error/index.js";
 import type { PragmaRuntime } from "../../runtime/index.js";
 import type { PackChildRow, PackEntity, PackLookup } from "../types.js";
 import {
@@ -56,10 +56,9 @@ export async function fetchGraphqlLookup(
       .join("; ");
     throw PragmaError.storeUnavailable(`GraphQL lookup failed: ${messages}`, {
       // `graph inspect` needs a <uri>; `ontology list` is runnable as-is.
-      recovery: cliRecovery(
-        "ontology list",
+      recovery: callRecovery(
+        { verb: "ontology list" },
         "Check the loaded ontology and namespaces.",
-        { tool: "ontology_list" },
       ),
     });
   }
@@ -72,8 +71,8 @@ export async function fetchGraphqlLookup(
     throw new PragmaError({
       code: "ENTITY_NOT_FOUND",
       message: `Cannot resolve <${entityUri}> — its rdf:type may be missing from the ontology.`,
-      recovery: cliRecovery(
-        `graph inspect ${entityUri}`,
+      recovery: callRecovery(
+        { verb: "graph inspect", params: { uri: entityUri } },
         "Inspect the entity's triples to check its rdf:type.",
       ),
     });

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

@@ -14,6 +14,7 @@ import { buildFixtureRuntime } from "../../testing/helpers/packRuntime.js";
 import type { PragmaRuntime, StoreSession } from "../runtime/types.js";
 import { compilePack } from "./compile.js";
 import { buildLookupDocument } from "./graphql/buildLookupDocument.js";
+import { fetchGraphqlLookup } from "./graphql/fetchGraphqlLookup.js";
 import type { LookupOutput } from "./resolveEntity.js";
 import { parsePackDefinition } from "./schema.js";
 import type { PackDefinition, PackLookup } from "./types.js";
@@ -320,6 +321,47 @@ describe("GraphQL engine — against the compiled fixture schema (PROTECTED)", (
 
   const lookup = GBLOCK.lookup as PackLookup;
 
+  /** The fixture runtime with its GraphQL executor replaced by a canned answer. */
+  const answering = (answer: unknown): PragmaRuntime =>
+    ({
+      ...rt,
+      query: { ...rt.query, graphql: async () => answer },
+    }) as PragmaRuntime;
+  const fetchWith = (answer: unknown) =>
+    fetchGraphqlLookup(
+      answering(answer),
+      lookup,
+      "https://ds.canonical.com/x",
+      "X",
+      "t",
+      BLOCK_PREFIXES,
+    );
+
+  it("an execution error recovers to the namespace list, in both spellings", async () => {
+    await expect(
+      fetchWith({ errors: [{ message: "boom" }] }),
+    ).rejects.toMatchObject({
+      code: "STORE_UNAVAILABLE",
+      recovery: {
+        cli: "pragma ontology list",
+        mcp: { tool: "ontology_list", params: {} },
+      },
+    });
+  });
+
+  it("a resolved IRI with no typed node recovers to inspecting THAT entity", async () => {
+    await expect(fetchWith({ data: { node: null } })).rejects.toMatchObject({
+      code: "ENTITY_NOT_FOUND",
+      recovery: {
+        cli: "pragma graph inspect https://ds.canonical.com/x",
+        mcp: {
+          tool: "graph_inspect",
+          params: { uri: "https://ds.canonical.com/x" },
+        },
+      },
+    });
+  });
+
   it("generates one document with derived names, Relay envelopes, subtype scoping", () => {
     const plan = buildLookupDocument(lookup, schema, "t");
     expect(plan.source).toContain("query PackLookup($uri: ID!)");

package/src/kernel/packs/iri.ts

@@ -7,7 +7,7 @@
  * before it can be interpolated into a generated `<iri>` query token.
  */
 
-import { cliRecovery, PragmaError } from "../error/index.js";
+import { callRecovery, PragmaError } from "../error/index.js";
 
 /** Characters not allowed inside a SPARQL `<IRI>`. */
 const UNSAFE_IRI_PATTERN = /[<>"{}|\\^`\s]/;
@@ -86,9 +86,10 @@ function tryResolveUri(
 
   return PragmaError.invalidInput("prefix", prefix, {
     validOptions: Object.keys(prefixes),
-    recovery: cliRecovery("ontology list", "List known ontology prefixes.", {
-      tool: "ontology_list",
-    }),
+    recovery: callRecovery(
+      { verb: "ontology list" },
+      "List known ontology prefixes.",
+    ),
   });
 }
 

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

@@ -46,7 +46,7 @@ ex:slider a ex:Widget ; ex:name "Slider" ; ex:kind "input" .
 /** The recovery a story authors for an EMPTY POPULATION — never for a filter. */
 const EMPTY_RECOVERY = {
   message: "No widgets in the store.",
-  cli: "sources update",
+  call: { verb: "sources update" },
 } as const;
 
 const WIDGET_LIST = {