@canonical/pragma-cli 0.27.0 → 0.29.0

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 };

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

@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vitest";
+import suggestNames from "./suggestNames.js";
+
+describe("suggestNames", () => {
+  it("T1-1: suggests edit-distance match for single-char typo", () => {
+    expect(suggestNames("Buton", ["Button", "Card", "Input"])).toEqual([
+      "Button",
+    ]);
+  });
+
+  it("T1-2: suggests dot-separated names with typo in last segment", () => {
+    const candidates = [
+      "react.component.props",
+      "react.component.props.wrapper",
+      "react.component.props.html_rendering",
+      "react.component.naming",
+      "css.selectors.namespace",
+    ];
+    const result = suggestNames("react.component.prosp", candidates);
+    expect(result.at(0)).toBe("react.component.props");
+    expect(result.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it("T1-3: matches case-insensitively, preserves original casing", () => {
+    expect(
+      suggestNames("buton-background", ["Button-Background", "color-primary"]),
+    ).toEqual(["Button-Background"]);
+  });
+
+  it("T1-4: returns prefix matches ranked first", () => {
+    const result = suggestNames("Accordion", [
+      "AccordionItem",
+      "AccordionGroup",
+      "Button",
+    ]);
+    expect(result).toHaveLength(2);
+    expect(result).toContain("AccordionItem");
+    expect(result).toContain("AccordionGroup");
+  });
+
+  it("T1-5: returns empty for completely unrelated input", () => {
+    expect(suggestNames("zzzzz", ["Button", "Card", "Input"])).toEqual([]);
+  });
+
+  it("T1-6: returns empty for empty query", () => {
+    expect(suggestNames("", ["Button"])).toEqual([]);
+  });
+
+  it("T1-7: excludes exact matches", () => {
+    expect(suggestNames("Button", ["Button", "Card"])).toEqual([]);
+  });
+
+  it("T1-8: ranks multiple candidates by distance", () => {
+    const result = suggestNames("Buttn", ["Button", "Butter", "Bitten"]);
+    expect(result).toContain("Button");
+    expect(result).toContain("Butter");
+    expect(result.indexOf("Button")).toBeLessThan(result.indexOf("Butter"));
+  });
+
+  it("respects maxResults option", () => {
+    const candidates = Array.from({ length: 20 }, (_, i) => `Item${i}`);
+    const result = suggestNames("Item", candidates, { maxResults: 3 });
+    expect(result.length).toBeLessThanOrEqual(3);
+  });
+
+  it("respects threshold option", () => {
+    const result = suggestNames("Buton", ["Button"], { threshold: 0.05 });
+    expect(result).toEqual([]);
+  });
+});

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

@@ -0,0 +1,97 @@
+/**
+ * Rank candidates by similarity to a failed lookup query.
+ *
+ * Returns up to {@link maxResults} names sorted by relevance:
+ * 1. Prefix matches (query is a case-insensitive prefix of candidate)
+ * 2. Edit-distance matches (Damerau-Levenshtein, normalized ≤ threshold)
+ *
+ * Exact matches are excluded — if the query exactly matches a candidate,
+ * the caller should have found it and never reached this function.
+ *
+ * @param query - The user-supplied name that failed lookup.
+ * @param candidates - All known names in the domain.
+ * @param opts.maxResults - Max suggestions to return (default: 5).
+ * @param opts.threshold - Max normalized edit distance (default: 0.4).
+ * @returns Ranked suggestions with original casing preserved.
+ */
+export default 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();
+
+  type Scored = { name: string; score: number };
+  const scored: Scored[] = [];
+
+  for (const candidate of candidates) {
+    const candidateLower = candidate.toLowerCase();
+
+    if (candidateLower === queryLower) continue;
+
+    if (candidateLower.startsWith(queryLower)) {
+      scored.push({ name: candidate, score: 0 });
+      continue;
+    }
+
+    const distance = damerauLevenshtein(queryLower, candidateLower);
+    const maxLen = Math.max(queryLower.length, candidateLower.length);
+    const normalized = maxLen === 0 ? 0 : distance / maxLen;
+
+    if (normalized <= threshold) {
+      scored.push({ name: candidate, score: normalized });
+    }
+  }
+
+  scored.sort((a, b) => a.score - b.score);
+  return scored.slice(0, maxResults).map((s) => s.name);
+}
+
+/**
+ * Damerau-Levenshtein distance between two strings.
+ *
+ * Counts insertions, deletions, substitutions, and adjacent transpositions.
+ */
+function damerauLevenshtein(a: string, b: string): number {
+  const lenA = a.length;
+  const lenB = b.length;
+
+  if (lenA === 0) return lenB;
+  if (lenB === 0) return lenA;
+
+  const matrix: number[][] = Array.from({ length: lenA + 1 }, () =>
+    Array.from<number>({ length: lenB + 1 }).fill(0),
+  );
+
+  for (let i = 0; i <= lenA; i++) {
+    matrix[i]![0] = i;
+  }
+  for (let j = 0; j <= lenB; j++) {
+    matrix[0]![j] = j;
+  }
+
+  for (let i = 1; i <= lenA; i++) {
+    for (let j = 1; j <= lenB; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+
+      matrix[i]![j] = Math.min(
+        matrix[i - 1]![j]! + 1, // deletion
+        matrix[i]![j - 1]! + 1, // insertion
+        matrix[i - 1]![j - 1]! + cost, // substitution
+      );
+
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+        matrix[i]![j] = Math.min(
+          matrix[i]![j]!,
+          matrix[i - 2]![j - 2]! + cost, // transposition
+        );
+      }
+    }
+  }
+
+  return matrix[lenA]![lenB]!;
+}

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

@@ -31,6 +31,7 @@ export type {
   OntologySummary,
 } from "./ontology.js";
 export type { PragmaRuntime } from "./runtime.js";
+export type { SampleOutput, SampleResult } from "./sample.js";
 export type {
   CategorySummary,
   CodeBlock,

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

@@ -2,14 +2,16 @@
 
 import type { Store } from "@canonical/ke";
 import type { PragmaConfig } from "#config";
+import type { SemanticPackage } from "../semanticPackage.js";
 
 /**
  * Boot-time state shared by CLI, MCP, and completions server.
  *
- * Four members:
+ * Five members:
  * - `store` — the ke triple store, loaded and ready for SPARQL queries.
  * - `config` — resolved pragma config (tier, channel).
  * - `cwd` — working directory used for config and source resolution.
+ * - `packages` — resolved semantic packages (for diagnostics and skills).
  * - `dispose()` — tears down the store and frees WASM memory. Must be
  *   called exactly once; calling operations after dispose is undefined.
  */
@@ -17,5 +19,6 @@ export interface PragmaRuntime {
   readonly store: Store;
   readonly config: PragmaConfig;
   readonly cwd: string;
+  readonly packages: readonly SemanticPackage[];
   dispose(): void;
 }

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

@@ -0,0 +1,17 @@
+/**
+ * Shared types for sample operations across domains.
+ *
+ * Sample returns 1–5 complete instances as exemplars so agents
+ * can learn actual data shapes before writing queries.
+ */
+
+/** Raw result from a sample operation — instances plus total count. */
+export interface SampleResult<T> {
+  readonly samples: readonly T[];
+  readonly totalCount: number;
+}
+
+/** Full sample output including agent guidance. */
+export interface SampleOutput<T> extends SampleResult<T> {
+  readonly nextSteps: readonly string[];
+}

package/src/domains/skill/helpers/resolveSkillSources.ts

@@ -1,7 +1,11 @@
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-import type { PackageRef } from "../../refs/operations/parseRef.js";
-import { resolvePackages } from "../../shared/packages.js";
+import { parsePackageEntry } from "../../refs/operations/parseRef.js";
+import {
+  createGitLoader,
+  createLocalLoader,
+} from "../../shared/loaders/index.js";
+import { DEFAULT_PACKAGES } from "../../shared/packages.js";
+import type { SemanticPackage } from "../../shared/semanticPackage.js";
+import { resolveSemanticPackages } from "../../shared/semanticPackage.js";
 
 /** A resolved skill source directory from an installed package. */
 export interface SkillSource {
@@ -12,27 +16,56 @@ export interface SkillSource {
 }
 
 /**
- * Resolve skill source directories from resolved packages.
+ * Resolve skill source directories from semantic packages.
  *
- * Auto-detects skills by checking for a `skills/` subdirectory
- * in each resolved package root.
+ * When `packages` is provided (from PragmaRuntime), extracts skill entries
+ * directly. Otherwise, resolves packages using local and git loaders
+ * (bundled loader is excluded since it has no filesystem skills).
  *
- * @param refs - Parsed package references. Omit for defaults.
+ * @param packages - Pre-resolved semantic packages (from boot).
  * @returns Array of resolved skill sources with absolute paths.
- * @note Impure
+ * @note Impure when packages is omitted (reads filesystem).
  */
 export default function resolveSkillSources(
-  refs?: ReadonlyArray<PackageRef>,
+  packages?: readonly SemanticPackage[],
+): SkillSource[] {
+  if (packages) {
+    return extractSkillSources(packages);
+  }
+
+  // Fallback: resolve packages ourselves (skills need filesystem paths,
+  // so we skip the bundled loader here)
+  return resolveSkillSourcesFromRefs();
+}
+
+function extractSkillSources(
+  packages: readonly SemanticPackage[],
 ): SkillSource[] {
   const sources: SkillSource[] = [];
-  const resolved = resolvePackages(refs);
+  for (const pkg of packages) {
+    for (const skill of pkg.skills) {
+      sources.push({ dir: skill.dir, packageName: pkg.name });
+    }
+  }
+  return sources;
+}
 
-  for (const { pkg, dir } of resolved) {
-    const skillsDir = join(dir, "skills");
-    if (existsSync(skillsDir)) {
-      sources.push({ dir: skillsDir, packageName: pkg });
+function resolveSkillSourcesFromRefs(): SkillSource[] {
+  const refs = DEFAULT_PACKAGES.map(parsePackageEntry);
+  const loaders = [createLocalLoader(), createGitLoader()];
+
+  // resolveSemanticPackages is async but skills resolution is sync.
+  // Use local+git loaders which are both sync.
+  const packages: SemanticPackage[] = [];
+  for (const ref of refs) {
+    for (const loader of loaders) {
+      const resolved = loader.resolve(ref);
+      if (resolved && !(resolved instanceof Promise)) {
+        packages.push(resolved);
+        break;
+      }
     }
   }
 
-  return sources;
+  return extractSkillSources(packages);
 }

package/src/domains/standard/commands/index.ts

@@ -1,5 +1,6 @@
-/** @module Re-exports standard command builders (`categories`, `get`, `list`). */
+/** @module Re-exports standard command builders (`categories`, `list`, `lookup`, `sample`). */
 
 export { default as categoriesCommand } from "./categories.js";
 export { default as listCommand } from "./list.js";
 export { default as lookupCommand } from "./lookup.js";
+export { default as sampleCommand } from "./sample.js";

package/src/domains/standard/commands/sample.ts

@@ -0,0 +1,57 @@
+/**
+ * Wires the `pragma standard sample` CLI command.
+ *
+ * Returns 1–5 complete standard instances as exemplars so agents
+ * can learn the data shape before writing queries.
+ */
+
+import {
+  type CommandDefinition,
+  createOutputResult,
+} from "@canonical/cli-core";
+import type { PragmaContext } from "../../shared/context.js";
+import { selectFormatter } from "../../shared/formatters.js";
+import type {
+  SampleOutput,
+  StandardDetailed,
+} from "../../shared/types/index.js";
+import { sampleFormatters } from "../formatters/index.js";
+import { sampleStandards } from "../operations/index.js";
+
+const NEXT_STEPS = [
+  "Use standard_lookup to inspect specific standards by name.",
+  "Use standard_list with --category to filter by category.",
+  "Use standard_categories to see all available categories.",
+];
+
+export default function sampleCommand(ctx: PragmaContext): CommandDefinition {
+  return {
+    path: ["standard", "sample"],
+    description:
+      "Return randomly selected complete standard instances as exemplars for shape discovery",
+    parameters: [
+      {
+        name: "count",
+        type: "string",
+        description: "Number of samples to return (1–5, default 2)",
+        required: false,
+      },
+    ],
+    meta: {
+      examples: ["pragma standard sample", "pragma standard sample --count 3"],
+    },
+    async execute(params) {
+      const count = Number(params.count ?? 2);
+      const result = await sampleStandards(ctx.store, count);
+
+      const output: SampleOutput<StandardDetailed> = {
+        ...result,
+        nextSteps: NEXT_STEPS,
+      };
+
+      return createOutputResult(output, {
+        plain: selectFormatter(ctx, sampleFormatters),
+      });
+    },
+  };
+}

package/src/domains/standard/formatters/index.ts

@@ -1,4 +1,4 @@
-/** @module Re-exports standard formatters (`categoriesFormatters`, `getFormatters`, `listFormatters`). */
+/** @module Re-exports standard formatters (`categoriesFormatters`, `listFormatters`, `lookupFormatters`, `sampleFormatters`). */
 
 export { default as categoriesFormatters } from "./categories.js";
 export { default as listFormatters } from "./list.js";
@@ -6,4 +6,5 @@ export {
   createInkLookupOptions,
   default as lookupFormatters,
 } from "./lookup.js";
+export { default as sampleFormatters } from "./sample.js";
 export type { StandardListOutput, StandardLookupInput } from "./types.js";

package/src/domains/standard/formatters/sample.ts

@@ -0,0 +1,15 @@
+/**
+ * Sample formatter for the standard domain.
+ *
+ * Delegates to the shared factory, rendering each item via the
+ * existing standard lookup formatter.
+ */
+
+import createSampleFormatters from "../../shared/sampleFormatters.js";
+import type { StandardDetailed } from "../../shared/types/index.js";
+import lookupFormatters from "./lookup.js";
+
+export default createSampleFormatters<StandardDetailed>(
+  "standards",
+  (standard, mode) => lookupFormatters[mode]({ standard, detailed: true }),
+);

package/src/domains/standard/index.ts

@@ -12,10 +12,16 @@ import {
   categoriesCommand,
   listCommand,
   lookupCommand,
+  sampleCommand,
 } from "./commands/index.js";
 
 export function commands(ctx: PragmaContext): CommandDefinition[] {
-  return [listCommand(ctx), lookupCommand(ctx), categoriesCommand(ctx)];
+  return [
+    listCommand(ctx),
+    lookupCommand(ctx),
+    categoriesCommand(ctx),
+    sampleCommand(ctx),
+  ];
 }
 
 export { specs as mcpSpecs } from "./mcp/index.js";
@@ -23,6 +29,7 @@ export {
   listCategories,
   listStandards,
   lookupStandard,
+  sampleStandards,
 } from "./operations/index.js";
 export {
   buildStandardFilters,

package/src/domains/standard/mcp/specs.ts

@@ -11,8 +11,9 @@ import {
   categoriesFormatters as standardCatFmt,
   listFormatters as standardListFmt,
   lookupFormatters as standardLookupFmt,
+  sampleFormatters as standardSampleFmt,
 } from "../formatters/index.js";
-import { listCategories } from "../operations/index.js";
+import { listCategories, sampleStandards } from "../operations/index.js";
 import {
   resolveStandardList,
   resolveStandardLookup,
@@ -192,6 +193,52 @@ const specs: readonly ToolSpec[] = [
       return { data: result, meta: { count: result.length } };
     },
   },
+
+  {
+    name: "standard_sample",
+    description:
+      "Return 1–5 randomly selected complete code standard instances as exemplars. Use BEFORE writing queries to see actual data shapes, property names, and value formats. Each call returns different instances.",
+    params: {
+      count: {
+        type: "string",
+        description: "Number of samples (1–5, default 2)",
+        optional: true,
+      },
+      condensed: {
+        type: "boolean",
+        description: "Token-optimized output",
+        optional: true,
+      },
+    },
+    readOnly: true,
+    async execute(rt, { count, condensed }) {
+      const n = Number(count ?? 2);
+      const result = await sampleStandards(rt.store, n);
+      const nextSteps = [
+        `These are ${result.samples.length} of ${result.totalCount} total standards.`,
+        "Use standard_lookup to inspect specific standards by name.",
+        "Use standard_list with category param to filter by category.",
+      ];
+
+      if (condensed) {
+        const text = standardSampleFmt.llm({ ...result, nextSteps });
+        return {
+          condensed: true,
+          text,
+          tokens: `~${Math.ceil(text.length / 4)}`,
+        };
+      }
+
+      return {
+        data: {
+          samples: result.samples,
+          totalCount: result.totalCount,
+          nextSteps,
+        },
+        meta: { count: result.samples.length },
+      };
+    },
+  },
 ];
 
 export default specs;

package/src/domains/standard/operations/index.ts

@@ -1,5 +1,6 @@
-/** @module Re-exports standard operations (`listCategories`, `getStandard`, `listStandards`). */
+/** @module Re-exports standard operations (`listCategories`, `listStandards`, `lookupStandard`, `sampleStandards`). */
 
 export { default as listCategories } from "./categories.js";
 export { default as listStandards } from "./list.js";
 export { default as lookupStandard } from "./lookup.js";
+export { default as sampleStandards } from "./sample.js";

package/src/domains/standard/operations/lookup.ts

@@ -18,6 +18,11 @@ import resolveUri from "../../graph/helpers/resolveUri.js";
 import { buildQuery } from "../../shared/buildQuery.js";
 import compactUri from "../../shared/compactUri.js";
 import { P } from "../../shared/prefixes.js";
+import {
+  detectCrossDomain,
+  listDomainNames,
+  suggestNames,
+} from "../../shared/suggestions/index.js";
 import type { CodeBlock, StandardDetailed } from "../../shared/types/index.js";
 
 export default async function lookupStandard(
@@ -52,12 +57,16 @@ export default async function lookupStandard(
   );
 
   if (baseResult.type !== "select" || baseResult.bindings.length === 0) {
+    const candidates = await listDomainNames(store, "standard");
+    const crossDomain = await detectCrossDomain(nameOrUri, "standard", store);
     throw PragmaError.notFound("standard", nameOrUri, {
+      suggestions: suggestNames(nameOrUri, candidates),
       recovery: {
         message: "List available standards.",
         cli: "pragma standard list",
         mcp: { tool: "standard_list" },
       },
+      crossDomain: crossDomain ?? undefined,
     });
   }