@canonical/pragma-cli 0.27.0 → 0.29.0

package/src/domains/graphql/operations/compileSchema.ts

@@ -0,0 +1,109 @@
+import { readFileSync } from "node:fs";
+import { createStore } from "@canonical/ke";
+import {
+  CompilationError,
+  type CompilerResult,
+  compile,
+  createStoreQueryFn,
+  type Diagnostic,
+  hashSources,
+} from "@canonical/ke-graphql";
+import { PragmaError } from "#error";
+import { resolveSourceFiles } from "../helpers/index.js";
+
+export interface CompileSchemaOptions {
+  /** TTL file paths or glob patterns, resolved from `cwd`. */
+  readonly sources: readonly string[];
+  /** Prefix map handed to both the ke store and the compiler. */
+  readonly prefixes: Readonly<Record<string, string>>;
+  /** Working directory for resolving relative source paths. */
+  readonly cwd: string;
+}
+
+export interface CompileSchemaResult {
+  /** `"ok"` when a schema was produced, `"failed"` when composition aborted. */
+  readonly status: "ok" | "failed";
+  /** All compiler diagnostics, including those carried by a CompilationError. */
+  readonly diagnostics: readonly Diagnostic[];
+  /** Resolved absolute TTL file paths that were loaded. */
+  readonly files: readonly string[];
+  /** Fingerprint of the raw source contents (matches ke's onLoad hashing). */
+  readonly sourcesHash: string;
+  /** Full compiler output; absent when compilation failed. */
+  readonly compiled?: CompilerResult;
+}
+
+/**
+ * Compile TTL sources into a GraphQL schema via the ke-graphql pipeline.
+ *
+ * Resolves source patterns, hashes the raw file contents (the exact bytes
+ * ke loads, so the artifact's `sourcesHash` matches what
+ * `createSchemaPlugin` computes from ke's onLoad), boots a throwaway ke
+ * store, and runs the compiler. A {@link CompilationError} (schema
+ * composition failed) is converted into a `"failed"` result carrying its
+ * diagnostics; the store is always disposed.
+ *
+ * @note Impure — reads filesystem and boots a ke store (WASM + TTL).
+ *
+ * @param options - Sources, prefixes, and working directory.
+ * @returns The compile outcome with diagnostics, files, and sources hash.
+ * @throws PragmaError with code `INVALID_INPUT` when no sources resolve.
+ * @throws PragmaError with code `STORE_ERROR` when the store fails to load.
+ */
+export default async function compileSchema(
+  options: CompileSchemaOptions,
+): Promise<CompileSchemaResult> {
+  const files = resolveSourceFiles(options.sources, options.cwd);
+
+  if (files.length === 0) {
+    throw PragmaError.invalidInput("sources", options.sources.join(", "), {
+      recovery: {
+        message: "Provide at least one existing TTL file or glob pattern.",
+      },
+    });
+  }
+
+  const contents = files.map((file) => readFileSync(file, "utf-8"));
+  const sourcesHash = hashSources(contents);
+
+  let store: Awaited<ReturnType<typeof createStore>>;
+  try {
+    store = await createStore({
+      sources: [...files],
+      prefixes: options.prefixes,
+      cwd: options.cwd,
+    });
+  } catch (error) {
+    throw PragmaError.storeError(
+      error instanceof Error ? error.message : String(error),
+      {
+        recovery: {
+          message: "Check the TTL syntax of the provided sources.",
+        },
+      },
+    );
+  }
+
+  try {
+    const compiled = await compile(createStoreQueryFn(store), options.prefixes);
+    return {
+      status: "ok",
+      diagnostics: compiled.diagnostics,
+      files,
+      sourcesHash,
+      compiled,
+    };
+  } catch (error) {
+    if (error instanceof CompilationError) {
+      return {
+        status: "failed",
+        diagnostics: error.diagnostics,
+        files,
+        sourcesHash,
+      };
+    }
+    throw error;
+  } finally {
+    store.dispose();
+  }
+}

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

@@ -0,0 +1,7 @@
+/** @module Barrel for graphql operations. */
+
+export type {
+  CompileSchemaOptions,
+  CompileSchemaResult,
+} from "./compileSchema.js";
+export { default as compileSchema } from "./compileSchema.js";

package/src/domains/graphql/types.ts

@@ -0,0 +1,29 @@
+/**
+ * Type definitions for the graphql domain.
+ *
+ * The compile report is the shared output shape for `graphql build` and
+ * `graphql check`: the full diagnostic list plus source and artifact
+ * metadata, rendered by the report formatters.
+ */
+
+import type { Diagnostic } from "@canonical/ke-graphql";
+
+/** Artifact paths written by `pragma graphql build`. */
+export interface GraphqlArtifacts {
+  /** Absolute path of the written GraphQL SDL file. */
+  readonly sdl: string;
+  /** Absolute path of the written extraction artifact. */
+  readonly extraction: string;
+}
+
+/** Output shape rendered by `graphql build` and `graphql check`. */
+export interface GraphqlCompileReport {
+  /** All compiler diagnostics (errors, warnings, info). */
+  readonly diagnostics: readonly Diagnostic[];
+  /** Resolved absolute TTL file paths that were compiled. */
+  readonly files: readonly string[];
+  /** Combined fingerprint of the raw TTL source contents. */
+  readonly sourcesHash: string;
+  /** Written artifact paths (present only for a successful `build`). */
+  readonly artifacts?: GraphqlArtifacts;
+}

package/src/domains/info/operations/collectInfo.test.ts

@@ -51,7 +51,7 @@ describe("collectInfo", () => {
 
   it("includes update information and store summary when available", async () => {
     const dispose = vi.fn();
-    bootStoreMock.mockResolvedValue({ dispose });
+    bootStoreMock.mockResolvedValue({ store: { dispose }, packages: [] });
     checkRegistryVersionMock.mockResolvedValue({
       latest: "9.9.9",
       distTag: "latest",
@@ -91,7 +91,7 @@ describe("collectInfo", () => {
   it("omits the update section when already on the latest version", async () => {
     const { VERSION } = await import("#constants");
     const dispose = vi.fn();
-    bootStoreMock.mockResolvedValue({ dispose });
+    bootStoreMock.mockResolvedValue({ store: { dispose }, packages: [] });
     checkRegistryVersionMock.mockResolvedValue({
       latest: VERSION,
       distTag: "latest",

package/src/domains/info/operations/collectInfo.ts

@@ -48,14 +48,14 @@ export default async function collectInfo(cwd: string): Promise<InfoData> {
   }
 
   let store: InfoData["store"];
-  let keStore: Awaited<ReturnType<typeof bootStore>> | undefined;
+  let bootResult: Awaited<ReturnType<typeof bootStore>> | undefined;
   try {
-    keStore = await bootStore({ cwd });
-    store = await collectStoreSummary(keStore);
+    bootResult = await bootStore({ cwd });
+    store = await collectStoreSummary(bootResult.store);
   } catch {
     // Store unavailable — show info without store section
   } finally {
-    keStore?.dispose();
+    bootResult?.store.dispose();
   }
 
   // Collect package ref summaries

package/src/domains/llm/capabilities.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from "vitest";
+import { VERSION } from "#constants";
+import { buildCapabilitiesCommand } from "./commands/index.js";
+import { TOOL_CATALOG } from "./data/index.js";
+import { buildCapabilitiesData } from "./mcp/index.js";
+
+describe("buildCapabilitiesData", () => {
+  it("returns correct version", () => {
+    const data = buildCapabilitiesData();
+    expect(data.version).toBe(VERSION);
+  });
+
+  it("includes conventions with three fields", () => {
+    const data = buildCapabilitiesData();
+    expect(data.conventions.system).toBeTruthy();
+    expect(data.conventions.model).toBeTruthy();
+    expect(data.conventions.querying).toBeTruthy();
+  });
+
+  it("includes a 3-stage discovery sequence", () => {
+    const data = buildCapabilitiesData();
+    expect(data.discovery_sequence).toHaveLength(3);
+    expect(data.discovery_sequence[0]?.stage).toBe(1);
+    expect(data.discovery_sequence[0]?.tool).toBe("capabilities");
+    expect(data.discovery_sequence[1]?.tool).toBe("*_sample");
+    expect(data.discovery_sequence[2]?.tool).toBe("domain tools");
+  });
+
+  it("includes all 29 tools from TOOL_CATALOG", () => {
+    const data = buildCapabilitiesData();
+    expect(data.tools).toHaveLength(TOOL_CATALOG.length);
+    expect(data.tools).toHaveLength(29);
+  });
+
+  it("every tool has a non-empty use_when", () => {
+    const data = buildCapabilitiesData();
+    for (const tool of data.tools) {
+      expect(tool.use_when.length).toBeGreaterThan(0);
+    }
+  });
+
+  it("counts match tool catalog category lengths", () => {
+    const data = buildCapabilitiesData();
+    expect(data.counts.total).toBe(29);
+    expect(data.counts.read).toBe(
+      TOOL_CATALOG.filter((t) => t.category === "read").length,
+    );
+    expect(data.counts.write).toBe(
+      TOOL_CATALOG.filter((t) => t.category === "write").length,
+    );
+    expect(data.counts.orientation).toBe(
+      TOOL_CATALOG.filter((t) => t.category === "orientation").length,
+    );
+    expect(data.counts.diagnostic).toBe(
+      TOOL_CATALOG.filter((t) => t.category === "diagnostic").length,
+    );
+  });
+
+  it("includes limits section", () => {
+    const data = buildCapabilitiesData();
+    expect(data.limits.output_modes).toContain("text");
+    expect(data.limits.output_modes).toContain("json");
+    expect(data.limits.output_modes).toContain("llm");
+    expect(data.limits.condensed_available).toBe(true);
+  });
+});
+
+describe("buildCapabilitiesCommand", () => {
+  it("returns an output result with plain renderer", async () => {
+    const cmd = buildCapabilitiesCommand();
+    expect(cmd.path).toEqual(["capabilities"]);
+
+    const result = await cmd.execute({}, {} as never);
+    expect(result.tag).toBe("output");
+    if (result.tag !== "output") throw new Error("Expected output result");
+
+    const text = result.render.plain(result.value) as string;
+    expect(text).toContain("Conventions");
+    expect(text).toContain("Discovery Sequence");
+    expect(text).toContain("block_list");
+    expect(text).toContain("read");
+    expect(text).toContain("29 tools");
+  });
+
+  it("does not require a store or runtime", async () => {
+    const cmd = buildCapabilitiesCommand();
+    // Execute with no context — should succeed because it's static
+    const result = await cmd.execute({}, {} as never);
+    expect(result.tag).toBe("output");
+  });
+});

package/src/domains/llm/commands/capabilities.ts

@@ -0,0 +1,28 @@
+import {
+  type CommandDefinition,
+  type CommandResult,
+  createOutputResult,
+} from "@canonical/cli-core";
+import renderCapabilities from "../formatters/capabilities.js";
+import { buildCapabilitiesData } from "../mcp/specs.js";
+
+/**
+ * Builds the `pragma capabilities` command definition.
+ *
+ * Returns a static system map: conventions, tool catalog with behavioral
+ * hints, discovery sequence, and output modes. No store needed.
+ *
+ * @returns A command definition for `capabilities`.
+ */
+export default function buildCapabilitiesCommand(): CommandDefinition {
+  return {
+    path: ["capabilities"],
+    description:
+      "Discover conventions, available tools, and discovery sequence",
+    parameters: [],
+    execute: async (): Promise<CommandResult> => {
+      const data = buildCapabilitiesData();
+      return createOutputResult(data, { plain: renderCapabilities });
+    },
+  };
+}

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

@@ -1,3 +1,4 @@
 /** @module Barrel for llm command builders. */
 
+export { default as buildCapabilitiesCommand } from "./capabilities.js";
 export { default as buildLlmCommand } from "./llm.js";

package/src/domains/llm/data/commandReference.ts

@@ -1,25 +1,97 @@
 import type { CommandRefEntry } from "../types.js";
+import { TOOL_CATALOG } from "./toolCatalog.js";
+
+/** Look up a use_when string from the tool catalog by MCP tool name. */
+function hintFor(mcpName: string): string {
+  return TOOL_CATALOG.find((t) => t.name === mcpName)?.use_when ?? "";
+}
 
 /**
- * Static command reference table with approximate token-cost estimates.
+ * Static command reference table with approximate token-cost estimates
+ * and behavioral hints for LLM tool selection.
  *
- * Used by the `pragma llm` orientation output to help LLMs budget context.
+ * Used by the `pragma llm` orientation output to help LLMs budget context
+ * and choose the right tool.
  */
 export const COMMAND_REFERENCE: readonly CommandRefEntry[] = [
-  { command: "block list", tokens: "~200" },
-  { command: "block lookup <name-or-iri...> --detailed", tokens: "~500" },
-  { command: "standard list --category <cat>", tokens: "~100" },
-  { command: "standard lookup <name-or-iri...> --detailed", tokens: "~400" },
-  { command: "standard categories", tokens: "~50" },
-  { command: "modifier list", tokens: "~100" },
-  { command: "modifier lookup <name-or-iri...>", tokens: "~80" },
-  { command: "token list", tokens: "~400" },
-  { command: "token lookup <name-or-iri...> --detailed", tokens: "~150" },
-  { command: "tier list", tokens: "~50" },
-  { command: "ontology list", tokens: "~80" },
-  { command: "ontology show <prefix>", tokens: "~300" },
-  { command: 'graph query "<sparql>"', tokens: "varies" },
-  { command: "graph inspect <uri>", tokens: "~200" },
-  { command: "config show", tokens: "~50" },
-  { command: "info", tokens: "~100" },
+  {
+    command: "block sample",
+    tokens: "~600",
+    use_when: hintFor("block_sample"),
+  },
+  { command: "block list", tokens: "~200", use_when: hintFor("block_list") },
+  {
+    command: "block lookup <name-or-iri...> --detailed",
+    tokens: "~500",
+    use_when: hintFor("block_lookup"),
+  },
+  {
+    command: "standard sample",
+    tokens: "~500",
+    use_when: hintFor("standard_sample"),
+  },
+  {
+    command: "standard list --category <cat>",
+    tokens: "~100",
+    use_when: hintFor("standard_list"),
+  },
+  {
+    command: "standard lookup <name-or-iri...> --detailed",
+    tokens: "~400",
+    use_when: hintFor("standard_lookup"),
+  },
+  {
+    command: "standard categories",
+    tokens: "~50",
+    use_when: hintFor("standard_categories"),
+  },
+  {
+    command: "modifier sample",
+    tokens: "~200",
+    use_when: hintFor("modifier_sample"),
+  },
+  {
+    command: "modifier list",
+    tokens: "~100",
+    use_when: hintFor("modifier_list"),
+  },
+  {
+    command: "modifier lookup <name-or-iri...>",
+    tokens: "~80",
+    use_when: hintFor("modifier_lookup"),
+  },
+  {
+    command: "token sample",
+    tokens: "~300",
+    use_when: hintFor("token_sample"),
+  },
+  { command: "token list", tokens: "~400", use_when: hintFor("token_list") },
+  {
+    command: "token lookup <name-or-iri...> --detailed",
+    tokens: "~150",
+    use_when: hintFor("token_lookup"),
+  },
+  { command: "tier list", tokens: "~50", use_when: hintFor("tier_list") },
+  {
+    command: "ontology list",
+    tokens: "~80",
+    use_when: hintFor("ontology_list"),
+  },
+  {
+    command: "ontology show <prefix>",
+    tokens: "~300",
+    use_when: hintFor("ontology_show"),
+  },
+  {
+    command: 'graph query "<sparql>"',
+    tokens: "varies",
+    use_when: hintFor("graph_query"),
+  },
+  {
+    command: "graph inspect <uri>",
+    tokens: "~200",
+    use_when: hintFor("graph_inspect"),
+  },
+  { command: "config show", tokens: "~50", use_when: hintFor("config_show") },
+  { command: "info", tokens: "~100", use_when: hintFor("info") },
 ];

package/src/domains/llm/data/decisionTrees.ts

@@ -9,21 +9,22 @@ import type { DecisionTree } from "../types.js";
 export const DECISION_TREES: readonly DecisionTree[] = [
   {
     intent: "Build a block",
-    tree: `? Know IRI or name?
-  yes → block lookup <name-or-iri...> --detailed  [~500]
-        e.g. block lookup ds:global.component.button
-  no  → block list [~200] → pick compact IRI → lookup`,
+    tree: `? First time seeing block data?
+  yes → block sample [~600] → see actual shapes, then query
+  no  → ? Know IRI or name?
+    yes → block lookup <name-or-iri...> --detailed  [~500]
+          e.g. block lookup ds:global.component.button
+    no  → block list [~200] → pick compact IRI → lookup`,
   },
   {
     intent: "Audit standards",
-    tree: `? Know standard IRI or name?
-  yes → standard lookup <name-or-iri...> --detailed [~400]
-        e.g. standard lookup react/component/props
-  no  → ? Know block IRI or name?
-      yes → block lookup <name-or-iri...> --detailed [~500]
-        → inspect related guidance manually Σ500
-        no  → standard list --category <cat> [~100]
-              → standard lookup <std-iri...> --detailed [~400] Σ500`,
+    tree: `? First time seeing standard data?
+  yes → standard sample [~500] → see actual shapes, then query
+  no  → ? Know standard IRI or name?
+    yes → standard lookup <name-or-iri...> --detailed [~400]
+          e.g. standard lookup react/component/props
+    no  → standard list --category <cat> [~100]
+          → standard lookup <std-iri...> --detailed [~400] Σ500`,
   },
   {
     intent: "Find a token",
@@ -34,7 +35,8 @@ export const DECISION_TREES: readonly DecisionTree[] = [
   },
   {
     intent: "Explore the design system",
-    tree: `high-level → ontology list [~80] → ontology show <ns> [~300]
+    tree: `first time → block sample / token sample / modifier sample [~300] → see real shapes
+high-level → ontology list [~80] → ontology show <ns> [~300]
 modifiers  → modifier list [~100] → modifier lookup <name-or-iri...> [~80]
 tiers      → tier list [~50]
 raw        → graph query "SELECT ..." → graph inspect <uri> [~200]`,

package/src/domains/llm/data/index.ts

@@ -2,3 +2,5 @@
 
 export { COMMAND_REFERENCE } from "./commandReference.js";
 export { DECISION_TREES } from "./decisionTrees.js";
+export type { ToolEntry } from "./toolCatalog.js";
+export { TOOL_CATALOG } from "./toolCatalog.js";

package/src/domains/llm/data/toolCatalog.ts

@@ -0,0 +1,184 @@
+/** Tool catalog with behavioral hints for agent orientation. */
+
+export interface ToolEntry {
+  readonly name: string;
+  readonly category: "read" | "write" | "orientation" | "diagnostic";
+  readonly use_when: string;
+}
+
+/** All registered MCP tools with category and behavioral guidance. */
+export const TOOL_CATALOG: readonly ToolEntry[] = [
+  // — Read ————————————————————————————————————————————————————————————————————
+  {
+    name: "block_list",
+    category: "read",
+    use_when:
+      "Browsing available components, patterns, layouts under current tier/channel",
+  },
+  {
+    name: "block_lookup",
+    category: "read",
+    use_when:
+      "Need full anatomy, modifiers, tokens, and standards for specific blocks by name or IRI",
+  },
+  {
+    name: "standard_list",
+    category: "read",
+    use_when:
+      "Browsing code standards, optionally filtered by category or search term",
+  },
+  {
+    name: "standard_lookup",
+    category: "read",
+    use_when:
+      "Need do/don't code examples for specific coding standards by name or IRI",
+  },
+  {
+    name: "standard_categories",
+    category: "read",
+    use_when: "Discovering which standard categories exist before filtering",
+  },
+  {
+    name: "modifier_list",
+    category: "read",
+    use_when: "Listing all modifier families and their allowed values",
+  },
+  {
+    name: "modifier_lookup",
+    category: "read",
+    use_when:
+      "Need values and usage details for specific modifier families by name",
+  },
+  {
+    name: "token_list",
+    category: "read",
+    use_when:
+      "Browsing design tokens, optionally filtered by category (color, spacing, etc.)",
+  },
+  {
+    name: "token_lookup",
+    category: "read",
+    use_when:
+      "Need theme values and resolution details for specific tokens by name or IRI",
+  },
+  {
+    name: "tier_list",
+    category: "read",
+    use_when: "Understanding the tier hierarchy before setting a tier filter",
+  },
+  {
+    name: "config_show",
+    category: "read",
+    use_when: "Checking active tier and channel before querying",
+  },
+  {
+    name: "ontology_list",
+    category: "read",
+    use_when:
+      "Discovering loaded namespaces, prefixes, and class/property counts",
+  },
+  {
+    name: "ontology_show",
+    category: "read",
+    use_when:
+      "Exploring the full schema of a namespace — classes, properties, and hierarchy",
+  },
+  {
+    name: "graph_query",
+    category: "read",
+    use_when:
+      "Complex SPARQL joins or aggregations that other tools cannot express",
+  },
+  {
+    name: "graph_inspect",
+    category: "read",
+    use_when:
+      "Examining all triples for a specific URI — predicates, objects, and types",
+  },
+  {
+    name: "skill_list",
+    category: "read",
+    use_when: "Discovering agent skills provided by installed packages",
+  },
+  {
+    name: "block_sample",
+    category: "read",
+    use_when:
+      "See actual block data shapes before querying — returns random instances each call, prevents guessing at property names",
+  },
+  {
+    name: "standard_sample",
+    category: "read",
+    use_when:
+      "See actual standard data shapes (with dos/donts) before querying — returns random instances each call",
+  },
+  {
+    name: "token_sample",
+    category: "read",
+    use_when:
+      "See actual token data shapes (with theme values) before querying — returns random instances each call",
+  },
+  {
+    name: "modifier_sample",
+    category: "read",
+    use_when:
+      "See actual modifier data shapes (with value lists) before querying — returns random instances each call",
+  },
+
+  // — Write ———————————————————————————————————————————————————————————————————
+  {
+    name: "config_tier",
+    category: "write",
+    use_when: "Setting or resetting the active tier filter",
+  },
+  {
+    name: "config_channel",
+    category: "write",
+    use_when:
+      "Setting the release channel (normal, experimental, or prerelease)",
+  },
+  {
+    name: "tokens_add_config",
+    category: "write",
+    use_when: "Generating a tokens.config.mjs for the terrazzo token pipeline",
+  },
+  {
+    name: "create_component",
+    category: "write",
+    use_when:
+      "Scaffolding a new design system component (React, Svelte, or Lit)",
+  },
+  {
+    name: "create_package",
+    category: "write",
+    use_when:
+      "Scaffolding a new npm package with proper monorepo configuration",
+  },
+
+  // — Orientation —————————————————————————————————————————————————————————————
+  {
+    name: "llm",
+    category: "orientation",
+    use_when:
+      "Need live context, decision trees, and command reference for design system work",
+  },
+  {
+    name: "capabilities",
+    category: "orientation",
+    use_when:
+      "Starting a session — understand conventions, available tools, and discovery flow",
+  },
+
+  // — Diagnostic ——————————————————————————————————————————————————————————————
+  {
+    name: "doctor",
+    category: "diagnostic",
+    use_when:
+      "Diagnosing environment issues — config, store, completions, MCP health",
+  },
+  {
+    name: "info",
+    category: "diagnostic",
+    use_when: "Checking pragma version, configuration summary, and store state",
+  },
+];