@canonical/pragma-cli 0.29.0 → 0.31.0

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

@@ -0,0 +1,156 @@
+import type { Store } from "@canonical/ke";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { createTestStore, DS_ALL_TTL } from "#testing";
+import listBlocks from "../../block/operations/list.js";
+import listModifiers from "../../modifier/operations/list.js";
+import { TTL_PREFIXES } from "../../shared/prefixes.js";
+import { standardPack } from "../../shared/stories/pack/bundled/standardPack.js";
+import runSelectQuery from "../../shared/stories/pack/runSelectQuery.js";
+import type { FilterConfig } from "../../shared/types/index.js";
+import listTokens from "../../token/operations/list.js";
+import { collectEntityCounts } from "./collectEntityCounts.js";
+
+/**
+ * The user-facing standard row count: the bundled pack's list query is
+ * what `standard list` serves since the standard cutover, so the info
+ * count must stay in lockstep with it (same WHERE grain the retired
+ * listStandards op used, including the OPTIONAL fan-out).
+ */
+async function countStandardRows(store: Store): Promise<number> {
+  const rows = await runSelectQuery(store, standardPack.list.query, "test");
+  return rows.length;
+}
+
+let store: Store;
+let cleanup: () => void;
+
+beforeAll(async () => {
+  const result = await createTestStore({ ttl: DS_ALL_TTL });
+  store = result.store;
+  cleanup = result.cleanup;
+});
+
+afterAll(() => cleanup());
+
+// The block count is the only filtered count, so its parity must hold under
+// every tier/channel combination the list op supports.
+const configs: Record<string, FilterConfig> = {
+  "no tier, prerelease": { tier: undefined, channel: "prerelease" },
+  "no tier, normal": { tier: undefined, channel: "normal" },
+  "global tier": { tier: "global", channel: "prerelease" },
+  "apps/lxd tier": { tier: "apps/lxd", channel: "normal" },
+};
+
+describe("collectEntityCounts", () => {
+  it.each(
+    Object.entries(configs),
+  )("matches legacy list-op lengths for %s", async (_label, config) => {
+    const counts = await collectEntityCounts(store, config);
+
+    expect(counts.blocks).toBe((await listBlocks(store, config)).length);
+    expect(counts.standards).toBe(await countStandardRows(store));
+    expect(counts.modifierFamilies).toBe((await listModifiers(store)).length);
+    expect(counts.tokens).toBe((await listTokens(store)).length);
+  });
+
+  it("returns positive counts on the full fixture", async () => {
+    const counts = await collectEntityCounts(store, {
+      tier: undefined,
+      channel: "prerelease",
+    });
+
+    expect(counts.blocks).toBeGreaterThan(0);
+    expect(counts.standards).toBeGreaterThan(0);
+    expect(counts.modifierFamilies).toBeGreaterThan(0);
+    expect(counts.tokens).toBeGreaterThan(0);
+  });
+});
+
+// A dedicated fan-out store (kept separate from the shared dsFixtures so its
+// enriched cardinality does not ripple into other suites). Every entity fans
+// its list op to MORE rows than there are distinct subjects, which is exactly
+// where a single-variable `COUNT(DISTINCT ?subject)` would undercount — so
+// these fixtures pin the grain-faithful subquery counts (FIX 4).
+const FAN_OUT_TTL = `
+${TTL_PREFIXES}
+
+# One block asserted as TWO types -> two GROUP BY (?component ?type ?name ?tier)
+# groups, so listBlocks emits two rows for a single subject.
+ds:fanout.multitype a ds:Component, ds:Pattern ;
+  ds:name "MultiType" ;
+  ds:tier ds:global ;
+  ds:release ds:stable .
+
+# A beta-only single-type block -> present under prerelease, filtered under
+# normal, so the block count also tracks channel scoping.
+ds:fanout.solo a ds:Component ;
+  ds:name "Solo" ;
+  ds:tier ds:global ;
+  ds:release ds:beta .
+
+# One modifier family with TWO names -> two GROUP BY (?family ?name) groups.
+ds:fanout.family a ds:ModifierFamily ;
+  ds:name "Alpha", "Beta" .
+
+# One standard in TWO categories -> the OPTIONAL hasCategory fans two rows.
+cs:fanout_cat_a a cs:Category ; cs:slug "cat-a" .
+cs:fanout_cat_b a cs:Category ; cs:slug "cat-b" .
+cs:fanout_std a cs:CodeStandard ;
+  cs:name "fanout/standard" ;
+  cs:description "A standard in two categories." ;
+  cs:hasCategory cs:fanout_cat_a, cs:fanout_cat_b .
+
+# One token with TWO token types -> the OPTIONAL tokenType fans two rows.
+ds:fanout_tt_a a ds:TokenType ; rdfs:label "TypeA" .
+ds:fanout_tt_b a ds:TokenType ; rdfs:label "TypeB" .
+ds:fanout.token a ds:Token ;
+  ds:tokenId "fanout.token" ;
+  ds:tokenType ds:fanout_tt_a, ds:fanout_tt_b .
+`;
+
+describe("collectEntityCounts fan-out parity", () => {
+  let fanStore: Store;
+  let fanCleanup: () => void;
+
+  beforeAll(async () => {
+    const result = await createTestStore({ ttl: FAN_OUT_TTL });
+    fanStore = result.store;
+    fanCleanup = result.cleanup;
+  });
+
+  afterAll(() => fanCleanup());
+
+  const fanConfigs: Record<string, FilterConfig> = {
+    prerelease: { tier: undefined, channel: "prerelease" },
+    normal: { tier: undefined, channel: "normal" },
+  };
+
+  it.each(
+    Object.entries(fanConfigs),
+  )("each count equals its legacy list-op length under %s channel", async (_label, config) => {
+    const counts = await collectEntityCounts(fanStore, config);
+
+    expect(counts.blocks).toBe((await listBlocks(fanStore, config)).length);
+    expect(counts.standards).toBe(await countStandardRows(fanStore));
+    expect(counts.modifierFamilies).toBe(
+      (await listModifiers(fanStore)).length,
+    );
+    expect(counts.tokens).toBe((await listTokens(fanStore)).length);
+  });
+
+  it("actually fans each entity beyond its distinct-subject count", async () => {
+    // These are the cardinalities a naive `COUNT(DISTINCT ?subject)` would
+    // undercount (blocks 3 vs 2 subjects, families 2 vs 1, etc.).
+    const config: FilterConfig = { tier: undefined, channel: "prerelease" };
+    expect((await listBlocks(fanStore, config)).length).toBe(3);
+    expect((await listModifiers(fanStore)).length).toBe(2);
+    expect(await countStandardRows(fanStore)).toBe(2);
+    expect((await listTokens(fanStore)).length).toBe(2);
+
+    // And under normal channel the beta block drops out (2 block rows).
+    expect(
+      (await listBlocks(fanStore, { tier: undefined, channel: "normal" }))
+        .length,
+    ).toBe(2);
+  });
+});

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

@@ -0,0 +1,123 @@
+import type { Store } from "@canonical/ke";
+import { buildQuery } from "../../shared/buildQuery.js";
+import { buildFilters } from "../../shared/filters/buildFilters.js";
+import { P } from "../../shared/prefixes.js";
+import type { FilterConfig } from "../../shared/types/index.js";
+import type { EntityCounts } from "../types.js";
+
+/**
+ * Run a `COUNT` query and parse its single `?count` binding.
+ *
+ * SPARQL `COUNT` yields a typed literal serialized as a string, so the
+ * value is parsed defensively and falls back to `0` when the query does
+ * not resolve to a select result.
+ *
+ * @param store - The ke store to query.
+ * @param query - A `SELECT (COUNT(...) AS ?count)` query string.
+ * @returns The parsed count, or `0` when unavailable.
+ * @note Queries ke store
+ */
+async function countRows(store: Store, query: string): Promise<number> {
+  const result = await store.query(buildQuery(query));
+  if (result.type !== "select") return 0;
+  const first = result.bindings[0];
+  return first ? Number.parseInt(first.count ?? "0", 10) || 0 : 0;
+}
+
+/**
+ * Count blocks, standards, modifier families, and tokens for the
+ * `pragma llm` orientation summary.
+ *
+ * Each `COUNT` reproduces the row cardinality of the matching leaf list
+ * operation, so the results equal `(await listX(...)).length` exactly:
+ *
+ * - **blocks** count the distinct `(?component, ?type, ?name, ?tier)` groups
+ *   `listBlocks` emits via `GROUP BY ?component ?type ?name ?tier`, so a
+ *   `COUNT(*)` over a `SELECT DISTINCT` of that exact grain (incl.
+ *   `buildFilters` for identical tier/channel scoping). This stays exact even
+ *   for a block asserted as several types or tiers, which would fan a
+ *   single-variable `COUNT(DISTINCT ?component)` short of the grouped rows.
+ * - **modifier families** count the distinct `(?family, ?name)` groups
+ *   `listModifiers` emits via `GROUP BY ?family ?name`, so a `COUNT(*)` over a
+ *   `SELECT DISTINCT` of that grain — exact even for a family with two names.
+ * - **standards** and **tokens** have no `GROUP BY` and an `OPTIONAL` that
+ *   fans rows out, so `COUNT(*)` over the identical `WHERE` matches row for
+ *   row (including the fan-out).
+ *
+ * @note Queries ke store
+ *
+ * @param store - The ke store to query.
+ * @param config - Filter config providing tier and channel settings.
+ * @returns Entity counts matching the four leaf list operations' lengths.
+ */
+async function collectEntityCounts(
+  store: Store,
+  config: FilterConfig,
+): Promise<EntityCounts> {
+  const filterClauses = buildFilters(config);
+
+  const [blocks, standards, modifierFamilies, tokens] = await Promise.all([
+    countRows(
+      store,
+      `
+      SELECT (COUNT(*) AS ?count)
+      WHERE {
+        SELECT DISTINCT ?component ?type ?name ?tier
+        WHERE {
+          VALUES ?type { ${P.ds}Component ${P.ds}Pattern ${P.ds}Layout ${P.ds}Subcomponent }
+          ?component a ?type ;
+                     ${P.ds}name ?name ;
+                     ${P.ds}tier ?tier .
+          ${filterClauses}
+        }
+      }
+    `,
+    ),
+    countRows(
+      store,
+      `
+      SELECT (COUNT(*) AS ?count)
+      WHERE {
+        ?standard a ${P.cs}CodeStandard ;
+                  ${P.cs}name ?name ;
+                  ${P.cs}description ?description .
+        OPTIONAL {
+          ?standard ${P.cs}hasCategory ?cat .
+          ?cat ${P.cs}slug ?categoryName .
+        }
+      }
+    `,
+    ),
+    countRows(
+      store,
+      `
+      SELECT (COUNT(*) AS ?count)
+      WHERE {
+        SELECT DISTINCT ?family ?name
+        WHERE {
+          ?family a ${P.ds}ModifierFamily ;
+                  ${P.ds}name ?name .
+        }
+      }
+    `,
+    ),
+    countRows(
+      store,
+      `
+      SELECT (COUNT(*) AS ?count)
+      WHERE {
+        ?token a ${P.ds}Token ;
+               ${P.ds}tokenId ?tokenId .
+        OPTIONAL {
+          ?token ${P.ds}tokenType ?type .
+          ?type ${P.rdfs}label ?typeName .
+        }
+      }
+    `,
+    ),
+  ]);
+
+  return { blocks, standards, modifierFamilies, tokens };
+}
+
+export { collectEntityCounts };

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

@@ -1,6 +1,6 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
-const readConfigMock = vi.fn();
+const readConfigLayersMock = vi.fn();
 const detectInstallSourceMock = vi.fn();
 const bootStoreMock = vi.fn();
 const checkRegistryVersionMock = vi.fn();
@@ -8,7 +8,7 @@ const collectStoreSummaryMock = vi.fn();
 
 vi.mock("#config", async (importOriginal) => ({
   ...(await importOriginal<typeof import("#config")>()),
-  readConfig: readConfigMock,
+  readConfigLayers: readConfigLayersMock,
 }));
 
 vi.mock("#package-manager", async (importOriginal) => {
@@ -46,7 +46,18 @@ describe("collectInfo", () => {
       scope: "global",
       label: "bun (global)",
     });
-    readConfigMock.mockReturnValue({ tier: "apps/lxd", channel: "normal" });
+    readConfigLayersMock.mockReturnValue({
+      config: { tier: "apps/lxd", channel: "normal" },
+      origins: {
+        tier: "project",
+        channel: "default",
+        packages: "default",
+        trace: "default",
+        framework: "default",
+      },
+      global: { path: "/home/u/.config/pragma/config.json", exists: false },
+      project: { path: "/repo/pragma.config.json", exists: true },
+    });
   });
 
   it("includes update information and store summary when available", async () => {

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

@@ -1,15 +1,14 @@
-import { readConfig } from "#config";
+import { readConfigLayers } from "#config";
 import { VERSION } from "#constants";
 import { detectInstallSource, PM_COMMANDS } from "#package-manager";
-import {
-  type PackageRef,
-  parsePackageEntry,
+import type {
+  PackageRef,
+  RawPackageEntry,
 } from "../../refs/operations/parseRef.js";
-import readGlobalRefs from "../../refs/operations/readGlobalRefs.js";
 import { bootStore } from "../../shared/bootStore.js";
 import { CHANNEL_RELEASES } from "../../shared/filters/buildChannelFilter.js";
 import { resolveTierChain } from "../../shared/filters/buildTierFilter.js";
-import { DEFAULT_PACKAGES } from "../../shared/packages.js";
+import { mergeAndParseRefs } from "../../shared/mergeAndParseRefs.js";
 import type { InfoData, PackageRefSummary } from "../types.js";
 import checkRegistryVersion from "./checkRegistryVersion.js";
 import { collectStoreSummary } from "./collectStoreSummary.js";
@@ -28,7 +27,8 @@ import { collectStoreSummary } from "./collectStoreSummary.js";
 export default async function collectInfo(cwd: string): Promise<InfoData> {
   const install = detectInstallSource();
   const pm = install.packageManager;
-  const config = readConfig(cwd);
+  const layers = readConfigLayers(cwd);
+  const config = layers.config;
   const tierChain = resolveTierChain(config.tier);
   const channelReleases = CHANNEL_RELEASES[config.channel];
 
@@ -65,7 +65,9 @@ export default async function collectInfo(cwd: string): Promise<InfoData> {
     version: VERSION,
     pm,
     installSource: install.label,
-    configPath: "pragma.config.json",
+    configPath: layers.project.exists
+      ? layers.project.path
+      : layers.global.path,
     tier: config.tier,
     tierChain,
     channel: config.channel,
@@ -78,14 +80,9 @@ export default async function collectInfo(cwd: string): Promise<InfoData> {
 }
 
 function collectPackageRefSummaries(
-  projectPackages?: ReadonlyArray<
-    string | { readonly name: string; readonly source?: string }
-  >,
+  configPackages?: ReadonlyArray<RawPackageEntry>,
 ): PackageRefSummary[] {
-  const entries = projectPackages ?? readGlobalRefs();
-  const raw = entries.length > 0 ? entries : DEFAULT_PACKAGES.map((pkg) => pkg);
-
-  return raw.map((entry) => refToSummary(parsePackageEntry(entry)));
+  return mergeAndParseRefs(configPackages).map(refToSummary);
 }
 
 function refToSummary(ref: PackageRef): PackageRefSummary {

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

@@ -1,5 +1,6 @@
 /** @module Barrel for info operations. */
 
 export { default as checkRegistryVersion } from "./checkRegistryVersion.js";
+export { collectEntityCounts } from "./collectEntityCounts.js";
 export { default as collectInfo } from "./collectInfo.js";
 export { collectStoreSummary } from "./collectStoreSummary.js";

package/src/domains/info/types.ts

@@ -52,3 +52,16 @@ export interface StoreSummary {
   readonly tripleCount: number;
   readonly graphNames: readonly string[];
 }
+
+/**
+ * Entity counts for the `pragma llm` orientation summary.
+ *
+ * Mirrors the row cardinality of the four leaf list operations
+ * (`listBlocks`, `listStandards`, `listModifiers`, `listTokens`).
+ */
+export interface EntityCounts {
+  readonly blocks: number;
+  readonly standards: number;
+  readonly modifierFamilies: number;
+  readonly tokens: number;
+}

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

@@ -1,9 +1,14 @@
 import { describe, expect, it } from "vitest";
 import { VERSION } from "#constants";
+import { TOKEN_READ_SURFACE_ENABLED } from "../token/featureFlag.js";
 import { buildCapabilitiesCommand } from "./commands/index.js";
 import { TOOL_CATALOG } from "./data/index.js";
 import { buildCapabilitiesData } from "./mcp/index.js";
 
+// token_list, token_lookup, and token_sample are gated behind the token
+// read-surface feature flag.
+const EXPECTED_TOOL_COUNT = TOKEN_READ_SURFACE_ENABLED ? 34 : 31;
+
 describe("buildCapabilitiesData", () => {
   it("returns correct version", () => {
     const data = buildCapabilitiesData();
@@ -26,10 +31,10 @@ describe("buildCapabilitiesData", () => {
     expect(data.discovery_sequence[2]?.tool).toBe("domain tools");
   });
 
-  it("includes all 29 tools from TOOL_CATALOG", () => {
+  it("includes every tool from TOOL_CATALOG", () => {
     const data = buildCapabilitiesData();
     expect(data.tools).toHaveLength(TOOL_CATALOG.length);
-    expect(data.tools).toHaveLength(29);
+    expect(data.tools).toHaveLength(EXPECTED_TOOL_COUNT);
   });
 
   it("every tool has a non-empty use_when", () => {
@@ -41,7 +46,7 @@ describe("buildCapabilitiesData", () => {
 
   it("counts match tool catalog category lengths", () => {
     const data = buildCapabilitiesData();
-    expect(data.counts.total).toBe(29);
+    expect(data.counts.total).toBe(EXPECTED_TOOL_COUNT);
     expect(data.counts.read).toBe(
       TOOL_CATALOG.filter((t) => t.category === "read").length,
     );
@@ -79,7 +84,22 @@ describe("buildCapabilitiesCommand", () => {
     expect(text).toContain("Discovery Sequence");
     expect(text).toContain("block_list");
     expect(text).toContain("read");
-    expect(text).toContain("29 tools");
+    expect(text).toContain(`${EXPECTED_TOOL_COUNT} tools`);
+  });
+
+  it("emits valid JSON when --format json is requested", async () => {
+    const cmd = buildCapabilitiesCommand();
+    const ctx = {
+      cwd: "/test",
+      globalFlags: { llm: false, format: "json" as const, verbose: false },
+    };
+
+    const result = await cmd.execute({}, ctx);
+    if (result.tag !== "output") throw new Error("Expected output result");
+
+    const text = result.render.plain(result.value) as string;
+    expect(() => JSON.parse(text)).not.toThrow();
+    expect(JSON.parse(text)).toMatchObject({ version: expect.any(String) });
   });
 
   it("does not require a store or runtime", async () => {

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

@@ -1,4 +1,5 @@
 import {
+  type CommandContext,
   type CommandDefinition,
   type CommandResult,
   createOutputResult,
@@ -10,7 +11,8 @@ 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.
+ * hints, discovery sequence, and output modes. No store needed. Honours
+ * `--format json` by emitting the structured payload so agents can parse it.
  *
  * @returns A command definition for `capabilities`.
  */
@@ -20,9 +22,16 @@ export default function buildCapabilitiesCommand(): CommandDefinition {
     description:
       "Discover conventions, available tools, and discovery sequence",
     parameters: [],
-    execute: async (): Promise<CommandResult> => {
+    execute: async (
+      _params: Record<string, unknown>,
+      ctx: CommandContext,
+    ): Promise<CommandResult> => {
       const data = buildCapabilitiesData();
-      return createOutputResult(data, { plain: renderCapabilities });
+      const asJson = ctx?.globalFlags?.format === "json";
+      return createOutputResult(data, {
+        plain: (value) =>
+          asJson ? JSON.stringify(value, null, 2) : renderCapabilities(value),
+      });
     },
   };
 }

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

@@ -31,7 +31,11 @@ export default function buildLlmCommand(ctx: PragmaContext): CommandDefinition {
         decisionTrees: DECISION_TREES,
         commandReference: COMMAND_REFERENCE,
       };
-      return createOutputResult(data, { plain: renderLlmOrientation });
+      const asJson = ctx?.globalFlags?.format === "json";
+      return createOutputResult(data, {
+        plain: (value) =>
+          asJson ? JSON.stringify(value, null, 2) : renderLlmOrientation(value),
+      });
     },
   };
 }

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

@@ -1,3 +1,4 @@
+import { TOKEN_READ_SURFACE_ENABLED } from "../../token/featureFlag.js";
 import type { CommandRefEntry } from "../types.js";
 import { TOOL_CATALOG } from "./toolCatalog.js";
 
@@ -60,17 +61,25 @@ export const COMMAND_REFERENCE: readonly CommandRefEntry[] = [
     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"),
-  },
+  ...(TOKEN_READ_SURFACE_ENABLED
+    ? ([
+        {
+          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"),
+        },
+      ] as const)
+    : []),
   { command: "tier list", tokens: "~50", use_when: hintFor("tier_list") },
   {
     command: "ontology list",

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

@@ -1,3 +1,4 @@
+import { TOKEN_READ_SURFACE_ENABLED } from "../../token/featureFlag.js";
 import type { DecisionTree } from "../types.js";
 
 /**
@@ -26,16 +27,20 @@ export const DECISION_TREES: readonly DecisionTree[] = [
     no  → standard list --category <cat> [~100]
           → standard lookup <std-iri...> --detailed [~400] Σ500`,
   },
-  {
-    intent: "Find a token",
-    tree: `? Know token IRI or name?
+  ...(TOKEN_READ_SURFACE_ENABLED
+    ? ([
+        {
+          intent: "Find a token",
+          tree: `? Know token IRI or name?
   yes → token lookup <name-or-iri...> --detailed [~150]
   no  → token list --category <cat> [~100]
         → token lookup <name-or-iri...> --detailed [~150] Σ250`,
-  },
+        },
+      ] as const)
+    : []),
   {
     intent: "Explore the design system",
-    tree: `first time → block sample / token sample / modifier sample [~300] → see real shapes
+    tree: `first time → block sample / ${TOKEN_READ_SURFACE_ENABLED ? "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]