@canonical/pragma-cli 0.36.0 → 0.38.0

package/src/kernel/project/cli/rootHelp.ts

@@ -83,6 +83,14 @@ function buildKernelGroups(programName: string): readonly HelpGroup[] {
         },
         { noun: "info", summary: "Show version, config, and update status" },
         { noun: "version", summary: "Print the CLI version" },
+        // A colophon is the note at the back of a book: the typeface, the
+        // press, the paper. Nothing depends on it, which is the point — so
+        // this line does not argue for it. Every other summary in this column
+        // promises work done; this one just invites you to look. It sits with
+        // the other commands that describe the distribution rather than act on
+        // it; "For AI agents" is for surfaces an agent drives, and credits are
+        // for a person reading.
+        { noun: "colophon", summary: "Read the credits" },
         {
           noun: "upgrade",
           summary: `Upgrade the ${programName} CLI to the latest version`,
@@ -96,11 +104,6 @@ function buildKernelGroups(programName: string): readonly HelpGroup[] {
           noun: "capabilities",
           summary: "Discover conventions, tools, and the discovery sequence",
         },
-        // A colophon is the note at the back of a book: the typeface, the
-        // press, the paper. Nothing depends on it, which is the point — so
-        // this line does not argue for it. Every other summary in this column
-        // promises work done; this one just invites you to look.
-        { noun: "colophon", summary: "Read the credits" },
         { noun: "skill", summary: "Browse agent skills from the active packs" },
         { noun: "prompt", summary: "Browse reusable prompt templates" },
         // Curated for PLACEMENT, not for existence: `mcp serve` is an

package/src/kernel/project/cli/suggest.test.ts

@@ -83,4 +83,39 @@ describe("suggestNames", () => {
   it("returns nothing for an empty query", () => {
     expect(suggestNames("", ["config"])).toEqual([]);
   });
+
+  it("returns nothing for a query that is only whitespace", () => {
+    expect(suggestNames("   ", ["config"])).toEqual([]);
+  });
+
+  it("never offers a candidate that IS the query once padding is ignored", () => {
+    // The reported defect, in the unit that produced the sentence:
+    // `block lookup Timeline` printed `Did you mean? - Timeline ` because 66
+    // shipped `ds:name` literals carry the source document's trailing space, and
+    // the exclusion compared the raw strings. A suggestion that differs from the
+    // query by a character no surface prints reads as the CLI refusing the word
+    // it just echoed — and if a candidate really is the query, the miss is the
+    // bug, so restating it would only hide the bug.
+    //
+    // The near-miss beside it is what proves the exclusion is the only thing
+    // dropped — an empty list would pass whether the rule worked or the
+    // threshold had simply swallowed both.
+    expect(suggestNames("Timeline", ["Timeline ", "Timelines"])).toEqual([
+      "Timelines",
+    ]);
+    // Both directions, and leading padding too: the query is the padded one
+    // here, and case is folded alongside.
+    expect(suggestNames("  timeline\t", ["Timeline", "Timelines"])).toEqual([
+      "Timelines",
+    ]);
+  });
+
+  it("suggests a padded candidate by its LITERAL value on a genuine typo", () => {
+    // Padding costs a candidate no edit distance, and the value handed back is
+    // the one the graph holds — the suggester matches loosely and quotes
+    // exactly, because a suggestion names something a reader can look up.
+    expect(suggestNames("Timelime", ["Timeline ", "block"])).toEqual([
+      "Timeline ",
+    ]);
+  });
 });

package/src/kernel/project/cli/suggestNames.ts

@@ -10,30 +10,43 @@
  * Return up to {@link maxResults} candidates most similar to `query`.
  *
  * Exact matches are excluded — a match means the caller should have resolved it
- * and never reached here.
+ * and never reached here. "Exact" is judged on the TRIMMED, case-folded token,
+ * which is the same equality the resolver's own name FILTER applies, so the two
+ * cannot disagree about whether a candidate is a match. They did:
+ * `block lookup Timeline` missed an entity whose `ds:name` ends in a space and
+ * then suggested "Timeline " back, which reads as the CLI declining to accept
+ * the word it just printed. Restating the query is never a useful suggestion —
+ * if a candidate really is the query, the miss is the bug and the suggestion
+ * would only hide it.
+ *
+ * Scoring reads the same trimmed forms, so padding costs a candidate no edit
+ * distance either; what is RETURNED is the candidate verbatim, padding and
+ * casing intact, because a suggestion names a value the graph holds.
  *
  * @param query - The token that failed to resolve.
  * @param candidates - All known names to rank against.
  * @param opts.maxResults - Max suggestions to return (default 5).
  * @param opts.threshold - Max normalized edit distance (default 0.4).
- * @returns Ranked suggestions, original casing preserved.
+ * @returns Ranked suggestions, original spelling preserved.
  */
 export function suggestNames(
   query: string,
   candidates: readonly string[],
   opts?: { maxResults?: number; threshold?: number },
 ): string[] {
-  if (query === "") return [];
-
   const maxResults = opts?.maxResults ?? 5;
   const threshold = opts?.threshold ?? 0.4;
-  const queryLower = query.toLowerCase();
+  const queryLower = query.trim().toLowerCase();
+
+  // A token that is nothing but whitespace has no word to rank against, the
+  // same as the empty one.
+  if (queryLower === "") return [];
 
   type Scored = { name: string; score: number };
   const scored: Scored[] = [];
 
   for (const candidate of candidates) {
-    const candidateLower = candidate.toLowerCase();
+    const candidateLower = candidate.trim().toLowerCase();
 
     if (candidateLower === queryLower) continue;
 
@@ -42,8 +55,22 @@ export function suggestNames(
       continue;
     }
 
-    const distance = damerauLevenshtein(queryLower, candidateLower);
     const maxLen = Math.max(queryLower.length, candidateLower.length);
+    // Skip on LENGTH before building a matrix. An edit distance is at least the
+    // difference in length, so a candidate whose length alone already exceeds
+    // the threshold cannot pass it — and the full Damerau-Levenshtein for it
+    // costs an O(n·m) matrix allocation. This changes no result, only the cost
+    // of reaching it: ranking one mistyped name against the shipped pack's
+    // 4,380 entities took 1.2 SECONDS, which is a long time to wait to be told
+    // about a typo.
+    if (
+      Math.abs(queryLower.length - candidateLower.length) >
+      threshold * maxLen
+    ) {
+      continue;
+    }
+
+    const distance = damerauLevenshtein(queryLower, candidateLower);
     const normalized = maxLen === 0 ? 0 : distance / maxLen;
 
     if (normalized <= threshold) {

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

@@ -156,7 +156,11 @@ function withDetail(
  */
 function noticeMeta(verb: VerbSpec, data: unknown): Record<string, unknown> {
   const notice = verb.output.formatters.notice?.(data as never);
-  return notice ? { notice } : {};
+  // The seam's machine half, merged here so an agent gets the tier scope as
+  // DATA (`meta.scope`) and not only as the sentence `notice` carries. The CLI
+  // merges the same seam into the same keys (`cli/dispatch.ts#renderData`).
+  const extra = verb.output.formatters.meta?.(data as never);
+  return { ...(extra ?? {}), ...(notice ? { notice } : {}) };
 }
 
 /** The tool handler for a read verb: run, project, envelope. */

package/src/kernel/render/contracts.ts

@@ -51,6 +51,8 @@ export interface SectionDef<T> {
   readonly heading: string;
   readonly kind: SectionKind;
   readonly showWhenEmpty?: boolean;
+  /** One sentence on how to READ the body, rendered under the heading. */
+  readonly note?: string;
 }
 
 /** A single inline field rendered in a lookup heading block. */

package/src/kernel/render/prefixes.test.ts

@@ -13,6 +13,8 @@ describe("DEFAULT_PREFIX_MAP", () => {
       skos: "http://www.w3.org/2004/02/skos/core#",
       ds: "https://ds.canonical.com/",
       cs: "http://pragma.canonical.com/codestandards#",
+      dt: "https://dt.canonical.com/",
+      "w3c-tokens": "https://dt.canonical.com/w3c-tokens/",
     });
   });
 

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

@@ -440,3 +440,46 @@ describe("section-body nesting follows CommonMark, not a near-enough reading", (
     expect(out).toMatch(/^### also inside$/m);
   });
 });
+
+describe("a section can say how to read its body", () => {
+  const entity = { anatomy: "background.color: [a, b]" };
+  const options = {
+    title: () => "Button",
+    fields: [],
+    sections: [
+      {
+        key: "anatomy" as const,
+        heading: "Anatomy (DSL)",
+        kind: "code" as const,
+        note: "A list value is the fallback chain, first wins.",
+      },
+    ],
+  };
+
+  it("puts the note between the heading and the body, once", () => {
+    const llm = renderLookupLlm(entity, options);
+    expect(llm).toContain(
+      "### Anatomy (DSL)\nA list value is the fallback chain, first wins.",
+    );
+    expect(llm.split("first wins")).toHaveLength(2);
+
+    const plain = renderLookupPlain(entity, options, styleFor(false));
+    expect(plain).toContain(
+      "Anatomy (DSL):\n  A list value is the fallback chain, first wins.",
+    );
+  });
+
+  it("renders nothing extra for a section that declares none", () => {
+    const bare = {
+      ...options,
+      sections: [
+        {
+          key: "anatomy" as const,
+          heading: "Anatomy (DSL)",
+          kind: "code" as const,
+        },
+      ],
+    };
+    expect(renderLookupLlm(entity, bare)).not.toContain("fallback chain");
+  });
+});

package/src/kernel/render/renderers.ts

@@ -189,12 +189,40 @@ function renderHeaderRow<T>(
   return style.enabled ? style.bold(line) : line;
 }
 
+/**
+ * Render a list as condensed Markdown.
+ *
+ * The heading COUNTS what the reader is looking at and — when the caller says
+ * so — admits that the count is not the population: `## Token (300, more
+ * exist)` rather than a bare `## Token (300)` that reads as a complete answer.
+ * The total is not named because it is not known: a page is cut with one extra
+ * row (`packs/runBodies.ts`), never with a second COUNT over the whole filtered
+ * population, so "more exist" is the strongest honest claim.
+ *
+ * The SCOPE is in the heading for the same reason, and it is the more serious
+ * of the two omissions: a truncated page at least ends where it ends, while a
+ * scoped read looks exactly like a complete one. `## Block (175, tier scope:
+ * global, apps, documentation, sites, stores)` says which part of the design
+ * system the 175 are, in the words `--tier` accepts.
+ *
+ * @param items - The rows on this page.
+ * @param options - Columns and empty-state copy.
+ * @param page - What the page knows about itself (`more`: further rows exist;
+ *   `scope`: the tiers it answered from, when it answered from some of them).
+ * @returns The formatted Markdown list.
+ */
 export function renderListLlm<T>(
   items: readonly T[],
   options: RenderListOptions<T>,
+  page: { readonly more?: boolean; readonly scope?: string } = {},
 ): string {
   const prefixes = options.prefixes ?? DEFAULT_PREFIX_MAP;
-  const lines = [`## ${options.heading} (${items.length})`, ""];
+  const count = [
+    `${items.length}`,
+    ...(page.more === true ? ["more exist"] : []),
+    ...(page.scope === undefined ? [] : [`tier scope: ${page.scope}`]),
+  ].join(", ");
+  const lines = [`## ${options.heading} (${count})`, ""];
 
   if (items.length === 0) {
     const body = emptyBody(options);
@@ -326,6 +354,11 @@ function renderLookupSections<T>(
         ? `${"#".repeat(SECTION_HEADING_LEVEL)} ${section.heading}`
         : `${section.heading}:`,
     );
+    // How to read what follows goes between the heading and the body — a
+    // notation's key is no use anywhere else.
+    if (section.note) {
+      sections.push(mode === "llm" ? section.note : indentBlock(section.note));
+    }
     sections.push(body);
   }