@canonical/pragma-cli 0.18.0

package/src/testing/fixtures/canonical.ttl

@@ -0,0 +1,437 @@
+
+@prefix ds: <https://ds.canonical.com/> .
+@prefix cs: <http://pragma.canonical.com/codestandards#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+# ---- Classes ----
+
+ds:UIBlock a owl:Class ;
+  rdfs:label "UI Block" .
+
+ds:Component a owl:Class ;
+  rdfs:subClassOf ds:UIBlock ;
+  rdfs:label "Component" .
+
+ds:Pattern a owl:Class ;
+  rdfs:subClassOf ds:UIBlock ;
+  rdfs:label "Pattern" .
+
+ds:Tier a owl:Class ;
+  rdfs:label "Tier" .
+
+ds:ModifierFamily a owl:Class ;
+  rdfs:label "Modifier Family" .
+
+ds:Modifier a owl:Class ;
+  rdfs:label "Modifier" .
+
+ds:Token a owl:Class ;
+  rdfs:label "Design Token" .
+
+ds:TokenType a owl:Class ;
+  rdfs:label "Token Type" .
+
+ds:ImplementationLibrary a owl:Class ;
+  rdfs:label "Implementation Library" .
+
+ds:ImplementationObject a owl:Class ;
+  rdfs:label "Implementation Object" .
+
+ds:BlockProperty a owl:Class ;
+  rdfs:label "Block Property" .
+
+ds:Subcomponent a owl:Class ;
+  rdfs:subClassOf ds:UIBlock ;
+  rdfs:label "Subcomponent" .
+
+cs:CodeStandard a owl:Class ;
+  rdfs:label "Code Standard" .
+
+cs:Category a owl:Class ;
+  rdfs:label "Standard Category" .
+
+# ---- Properties ----
+
+ds:name a owl:DatatypeProperty ;
+  rdfs:domain ds:UIBlock ;
+  rdfs:range xsd:string .
+
+ds:tier a owl:ObjectProperty ;
+  rdfs:domain ds:UIBlock .
+
+ds:release a owl:ObjectProperty ;
+  rdfs:domain ds:UIBlock .
+
+ds:hasModifierFamily a owl:ObjectProperty ;
+  rdfs:domain ds:UIBlock ;
+  rdfs:range ds:ModifierFamily .
+
+ds:modifierFamily a owl:ObjectProperty ;
+  rdfs:domain ds:Modifier ;
+  rdfs:range ds:ModifierFamily .
+
+ds:tokenId a owl:DatatypeProperty ;
+  rdfs:domain ds:Token ;
+  rdfs:range xsd:string .
+
+ds:tokenType a owl:ObjectProperty ;
+  rdfs:domain ds:Token ;
+  rdfs:range ds:TokenType .
+
+ds:tokenTier a owl:ObjectProperty ;
+  rdfs:domain ds:Token .
+
+ds:valueLight a owl:DatatypeProperty ;
+  rdfs:domain ds:Token ;
+  rdfs:range xsd:string .
+
+ds:valueDark a owl:DatatypeProperty ;
+  rdfs:domain ds:Token ;
+  rdfs:range xsd:string .
+
+ds:platform a owl:DatatypeProperty ;
+  rdfs:domain ds:ImplementationLibrary ;
+  rdfs:range xsd:string .
+
+ds:libraryName a owl:DatatypeProperty ;
+  rdfs:domain ds:ImplementationLibrary ;
+  rdfs:range xsd:string .
+
+ds:hasImplementation a owl:ObjectProperty ;
+  rdfs:domain ds:ImplementationLibrary ;
+  rdfs:range ds:ImplementationObject .
+
+ds:implementsBlock a owl:ObjectProperty ;
+  rdfs:domain ds:ImplementationObject ;
+  rdfs:range ds:UIBlock .
+
+ds:headLink a owl:DatatypeProperty ;
+  rdfs:domain ds:ImplementationObject ;
+  rdfs:range xsd:string .
+
+ds:usesToken a owl:ObjectProperty ;
+  rdfs:domain ds:UIBlock ;
+  rdfs:range ds:Token .
+
+ds:anatomyNode a owl:ObjectProperty ;
+  rdfs:domain ds:UIBlock .
+
+ds:summary a owl:DatatypeProperty ;
+  rdfs:domain ds:UIBlock ;
+  rdfs:range xsd:string .
+
+ds:whenToUse a owl:DatatypeProperty ;
+  rdfs:domain ds:UIBlock ;
+  rdfs:range xsd:string .
+
+ds:whenNotToUse a owl:DatatypeProperty ;
+  rdfs:domain ds:UIBlock ;
+  rdfs:range xsd:string .
+
+ds:guidelines a owl:DatatypeProperty ;
+  rdfs:domain ds:UIBlock ;
+  rdfs:range xsd:string .
+
+ds:anatomyDsl a owl:DatatypeProperty ;
+  rdfs:domain ds:UIBlock ;
+  rdfs:range xsd:string .
+
+ds:anatomyClassic a owl:DatatypeProperty ;
+  rdfs:domain ds:UIBlock ;
+  rdfs:range xsd:string .
+
+ds:figmaLink a owl:DatatypeProperty ;
+  rdfs:domain ds:UIBlock ;
+  rdfs:range xsd:string .
+
+ds:hasProperty a owl:ObjectProperty ;
+  rdfs:domain ds:UIBlock ;
+  rdfs:range ds:BlockProperty .
+
+ds:propertyType a owl:DatatypeProperty ;
+  rdfs:domain ds:BlockProperty ;
+  rdfs:range xsd:string .
+
+ds:optional a owl:DatatypeProperty ;
+  rdfs:domain ds:BlockProperty ;
+  rdfs:range xsd:boolean .
+
+ds:defaultValue a owl:DatatypeProperty ;
+  rdfs:domain ds:BlockProperty ;
+  rdfs:range xsd:string .
+
+ds:constraints a owl:DatatypeProperty ;
+  rdfs:domain ds:BlockProperty ;
+  rdfs:range xsd:string .
+
+ds:hasSubcomponent a owl:ObjectProperty ;
+  rdfs:domain ds:UIBlock ;
+  rdfs:range ds:Subcomponent .
+
+cs:name a owl:DatatypeProperty ;
+  rdfs:domain cs:CodeStandard ;
+  rdfs:range xsd:string .
+
+cs:hasCategory a owl:ObjectProperty ;
+  rdfs:domain cs:CodeStandard ;
+  rdfs:range cs:Category .
+
+cs:slug a owl:DatatypeProperty ;
+  rdfs:domain cs:Category ;
+  rdfs:range xsd:string .
+
+cs:description a owl:DatatypeProperty ;
+  rdfs:domain cs:CodeStandard ;
+  rdfs:range xsd:string .
+
+cs:Example a owl:Class .
+
+cs:do a owl:ObjectProperty ;
+  rdfs:domain cs:CodeStandard ;
+  rdfs:range cs:Example .
+
+cs:dont a owl:ObjectProperty ;
+  rdfs:domain cs:CodeStandard ;
+  rdfs:range cs:Example .
+
+cs:language a owl:DatatypeProperty ;
+  rdfs:domain cs:Example ;
+  rdfs:range xsd:string .
+
+cs:code a owl:DatatypeProperty ;
+  rdfs:domain cs:Example ;
+  rdfs:range xsd:string .
+
+cs:extends a owl:ObjectProperty ;
+  rdfs:domain cs:CodeStandard ;
+  rdfs:range cs:CodeStandard .
+
+
+@prefix ds: <https://ds.canonical.com/> .
+
+ds:global a ds:Tier ;
+  ds:name "global" .
+
+ds:apps a ds:Tier ;
+  ds:name "apps" .
+
+ds:apps_lxd a ds:Tier ;
+  ds:name "apps/lxd" .
+
+
+@prefix ds: <https://ds.canonical.com/> .
+
+ds:stable a ds:ReleaseChannel .
+ds:experimental a ds:ReleaseChannel .
+ds:alpha a ds:ReleaseChannel .
+ds:beta a ds:ReleaseChannel .
+
+
+@prefix ds: <https://ds.canonical.com/> .
+
+ds:global.component.button a ds:Component ;
+  ds:name "Button" ;
+  ds:tier ds:global ;
+  ds:release ds:stable ;
+  ds:summary "Primary action trigger with optional icon and label." ;
+  ds:whenToUse "Use for high-priority actions in forms and flows." ;
+  ds:whenNotToUse "Avoid for low-emphasis tertiary actions." ;
+  ds:guidelines "Keep labels concise and pair icons with text when possible." ;
+  ds:anatomyDsl "root: button; children: label, icon" ;
+  ds:anatomyClassic "button > label + icon" ;
+  ds:figmaLink "https://figma.com/design/example/Button" ;
+  ds:hasModifierFamily ds:modifier_family.importance ;
+  ds:hasModifierFamily ds:modifier_family.density ;
+  ds:usesToken ds:token.color.primary ;
+  ds:anatomyNode ds:global.component.button.node.root ;
+  ds:anatomyNode ds:global.component.button.node.label ;
+  ds:anatomyNode ds:global.component.button.node.icon ;
+  ds:hasProperty [
+    a ds:BlockProperty ;
+    ds:name "disabled" ;
+    ds:propertyType "boolean" ;
+    ds:optional true ;
+    ds:defaultValue "false" ;
+    ds:constraints "Disables click and keyboard activation."
+  ] , [
+    a ds:BlockProperty ;
+    ds:name "loading" ;
+    ds:propertyType "boolean" ;
+    ds:optional true ;
+    ds:defaultValue "false" ;
+    ds:constraints "Shows busy state and suppresses duplicate actions."
+  ] ;
+  ds:hasSubcomponent ds:global.subcomponent.button.icon .
+
+ds:global.component.button.node.root a ds:AnatomyNode ;
+  ds:name "button" .
+
+ds:global.component.button.node.label a ds:AnatomyNode ;
+  ds:name "label" .
+
+ds:global.component.button.node.icon a ds:AnatomyNode ;
+  ds:name "icon" .
+
+ds:global.subcomponent.button.icon a ds:Subcomponent ;
+  ds:name "Button Icon" ;
+  ds:tier ds:global ;
+  ds:release ds:stable .
+
+ds:global.component.card a ds:Component ;
+  ds:name "Card" ;
+  ds:tier ds:global ;
+  ds:release ds:stable ;
+  ds:summary "Contained surface for related content and actions." ;
+  ds:anatomyDsl "root: card; children: header, body" ;
+  ds:hasProperty [
+    a ds:BlockProperty ;
+    ds:name "padding" ;
+    ds:propertyType "dimension" ;
+    ds:optional true ;
+    ds:defaultValue "spacing.md" ;
+    ds:constraints "Use design token references for spacing values."
+  ] .
+
+ds:apps.lxd.component.panel a ds:Component ;
+  ds:name "LXD Panel" ;
+  ds:tier ds:apps_lxd ;
+  ds:release ds:stable .
+
+ds:global.component.beta-widget a ds:Component ;
+  ds:name "Beta Widget" ;
+  ds:tier ds:global ;
+  ds:release ds:beta .
+
+
+@prefix ds: <https://ds.canonical.com/> .
+
+ds:impl.react a ds:ImplementationLibrary ;
+  ds:libraryName "@canonical/react-ds-global" ;
+  ds:platform "react" ;
+  ds:hasImplementation [
+    a ds:ImplementationObject ;
+    ds:implementsBlock ds:global.component.button ;
+    ds:headLink "src/lib/Button/Button.tsx"
+  ] , [
+    a ds:ImplementationObject ;
+    ds:implementsBlock ds:global.component.card ;
+    ds:headLink "src/lib/Card/Card.tsx"
+  ] .
+
+ds:impl.svelte a ds:ImplementationLibrary ;
+  ds:libraryName "@canonical/svelte-ds-global" ;
+  ds:platform "svelte" .
+
+
+@prefix cs: <http://pragma.canonical.com/codestandards#> .
+
+cs:react_category a cs:Category ;
+  cs:slug "react" .
+
+cs:code_category a cs:Category ;
+  cs:slug "code" .
+
+cs:react_folder a cs:CodeStandard ;
+  cs:name "react/component/folder-structure" ;
+  cs:hasCategory cs:react_category ;
+  cs:description "Components must follow the standard folder layout" ;
+  cs:do [
+    cs:description "Place component files in src/lib/ComponentName/" ;
+    cs:language "typescript" ;
+    cs:code "src/lib/Button/Button.tsx"
+  ] ;
+  cs:do [
+    cs:description "Include index.ts barrel export" ;
+    cs:language "typescript" ;
+    cs:code "export { default } from './Button.js';"
+  ] ;
+  cs:dont [
+    cs:description "Use flat directory with all components at same level" ;
+    cs:language "typescript" ;
+    cs:code "src/lib/Button.tsx"
+  ] .
+
+cs:react_props a cs:CodeStandard ;
+  cs:name "react/component/props" ;
+  cs:hasCategory cs:react_category ;
+  cs:extends cs:react_folder ;
+  cs:description "Props must extend the base HTML element type" ;
+  cs:do [
+    cs:description "Extend HTMLAttributes<HTMLElement>" ;
+    cs:language "typescript" ;
+    cs:code "interface ButtonProps extends HTMLAttributes<HTMLButtonElement> {}"
+  ] ;
+  cs:dont [
+    cs:description "Define props without extending HTML attributes" ;
+    cs:language "typescript" ;
+    cs:code "interface ButtonProps { onClick: () => void }"
+  ] .
+
+cs:code_purity a cs:CodeStandard ;
+  cs:name "code/function/purity" ;
+  cs:hasCategory cs:code_category ;
+  cs:description "Functions should be pure where possible" ;
+  cs:do [
+    cs:description "Return same output for same input" ;
+    cs:language "typescript" ;
+    cs:code "function add(a: number, b: number) { return a + b; }"
+  ] ;
+  cs:dont [
+    cs:description "Modify external state without annotation" ;
+    cs:language "typescript" ;
+    cs:code "let count = 0; function increment() { count++; }"
+  ] .
+
+
+@prefix ds: <https://ds.canonical.com/> .
+
+ds:modifier_family.importance a ds:ModifierFamily ;
+  ds:name "importance" .
+
+ds:mod_importance_default a ds:Modifier ;
+  ds:name "default" ;
+  ds:modifierFamily ds:modifier_family.importance .
+
+ds:mod_importance_primary a ds:Modifier ;
+  ds:name "primary" ;
+  ds:modifierFamily ds:modifier_family.importance .
+
+ds:mod_importance_secondary a ds:Modifier ;
+  ds:name "secondary" ;
+  ds:modifierFamily ds:modifier_family.importance .
+
+ds:modifier_family.density a ds:ModifierFamily ;
+  ds:name "density" .
+
+ds:mod_density_default a ds:Modifier ;
+  ds:name "default" ;
+  ds:modifierFamily ds:modifier_family.density .
+
+ds:mod_density_compact a ds:Modifier ;
+  ds:name "compact" ;
+  ds:modifierFamily ds:modifier_family.density .
+
+
+@prefix ds: <https://ds.canonical.com/> .
+
+ds:token_type.color a ds:TokenType ;
+  rdfs:label "Color" .
+
+ds:token_type.dimension a ds:TokenType ;
+  rdfs:label "Dimension" .
+
+ds:token.color.primary a ds:Token ;
+  ds:tokenId "color.primary" ;
+  ds:tokenType ds:token_type.color ;
+  ds:tokenTier ds:token_tier.semantic ;
+  ds:valueLight "#0066cc" ;
+  ds:valueDark "#4d9aff" .
+
+ds:token.spacing.sm a ds:Token ;
+  ds:tokenId "spacing.sm" ;
+  ds:tokenType ds:token_type.dimension ;
+  ds:tokenTier ds:token_tier.primitive ;
+  ds:valueLight "8px" ;
+  ds:valueDark "8px" .

package/src/testing/fixtures/filtered-config.json

@@ -0,0 +1,4 @@
+{
+  "tier": "apps/lxd",
+  "channel": "normal"
+}

package/src/testing/fixtures.ts

@@ -0,0 +1,34 @@
+/**
+ * Test fixtures for configuration parsing and package-manager detection.
+ *
+ * Groups sample config strings and mock binary paths used by
+ * unit tests across the config and package-manager domains.
+ */
+
+/** Full config with both tier and channel set. */
+const SAMPLE_CONFIG_FULL = `tier = "apps/lxd"
+channel = "experimental"
+`;
+
+/** Config with only the tier field set. */
+const SAMPLE_CONFIG_TIER_ONLY = `tier = "global"
+`;
+
+/** Empty config — no tier, no channel override. */
+const SAMPLE_CONFIG_EMPTY = "";
+
+/** Mock pragma binary paths keyed by package manager name. */
+const MOCK_BIN_PATHS: Record<string, string> = {
+  bun: "/home/user/.bun/install/global/node_modules/.bin/pragma",
+  pnpm: "/home/user/.local/share/pnpm/global/5/node_modules/.bin/pragma",
+  yarn: "/home/user/.yarn/bin/pragma",
+  npm: "/home/user/.config/nvm/versions/node/v24/bin/pragma",
+  local: "/project/node_modules/.bin/pragma",
+};
+
+export {
+  SAMPLE_CONFIG_FULL,
+  SAMPLE_CONFIG_TIER_ONLY,
+  SAMPLE_CONFIG_EMPTY,
+  MOCK_BIN_PATHS,
+};

package/src/testing/helpers/assertParity.ts

@@ -0,0 +1,28 @@
+import { expect } from "vitest";
+
+/**
+ * Assert that an MCP tool response's `data` field is deeply equal
+ * to the operation result that CLI would produce.
+ *
+ * Unwraps the MCP response envelope and deep-compares `data` against
+ * the raw operation result. Fails with a clear diff on mismatch.
+ *
+ * @param operationResult - The raw result from calling the shared operation.
+ * @param mcpResponse - The raw MCP `CallToolResult` from `client.callTool()`.
+ * @throws When the envelope is not `ok: true` or `data` does not match.
+ */
+export default function assertParity(
+  operationResult: unknown,
+  mcpResponse: Record<string, unknown>,
+): void {
+  const content = mcpResponse.content as unknown[];
+  const first = content[0] as { type: string; text: string };
+  expect(first.type).toBe("text");
+
+  const envelope = JSON.parse(first.text) as {
+    ok: boolean;
+    data?: unknown;
+  };
+  expect(envelope.ok).toBe(true);
+  expect(envelope.data).toEqual(operationResult);
+}

package/src/testing/helpers/createTestMcpClient.ts

@@ -0,0 +1,40 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import type { PragmaRuntime } from "../../domains/shared/runtime.js";
+import { createMcpServerFromRuntime } from "../../mcp/createMcpServer.js";
+import type { TestMcpClientResult } from "../types.js";
+
+/**
+ * Create an in-process MCP client connected to a server backed by
+ * the given runtime.
+ *
+ * Uses `createMcpServerFromRuntime` and the MCP SDK's in-memory
+ * transport. No network, no stdio. The caller owns the runtime
+ * lifecycle and must call `cleanup` when done.
+ *
+ * @param runtime - An already-booted pragma runtime.
+ * @returns The connected client and a cleanup function.
+ *
+ * @note Impure
+ */
+export default async function createTestMcpClient(
+  runtime: PragmaRuntime,
+): Promise<TestMcpClientResult> {
+  const { server } = createMcpServerFromRuntime(runtime);
+
+  const [serverTransport, clientTransport] =
+    InMemoryTransport.createLinkedPair();
+
+  const client = new Client({ name: "pragma-test-client", version: "0.0.0" });
+
+  await server.connect(serverTransport);
+  await client.connect(clientTransport);
+
+  return {
+    client,
+    cleanup: async () => {
+      await client.close();
+      await server.close();
+    },
+  };
+}

package/src/testing/helpers/createTestRuntime.ts

@@ -0,0 +1,67 @@
+import { copyFileSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { PragmaRuntime } from "../../domains/shared/runtime.js";
+import { bootPragma } from "../../domains/shared/runtime.js";
+
+const FIXTURES_DIR = new URL("../fixtures/", import.meta.url).pathname;
+const CANONICAL_TTL = join(FIXTURES_DIR, "canonical.ttl");
+
+type ConfigName = "canonical-config.json" | "filtered-config.json";
+
+/**
+ * Create a PragmaRuntime backed by the canonical test fixture.
+ *
+ * Stages the selected config as `pragma.config.json` in a temp directory
+ * and calls the real `bootPragma()` with a sources override pointing at
+ * `testing/fixtures/canonical.ttl`. No mocks. Each call creates an
+ * independent runtime. The caller owns disposal.
+ *
+ * @param options - Optional configuration overrides.
+ * @param options.config - Config file name within the fixtures directory.
+ *   Defaults to `"canonical-config.json"` (tier=global, channel=normal).
+ *   Use `"filtered-config.json"` for tier-filtering tests (apps/lxd).
+ * @returns A fully booted PragmaRuntime whose `dispose` also cleans up
+ *   the temporary directory.
+ *
+ * @example
+ * const rt = await createTestRuntime();
+ * const blocks = await listBlocks(rt.store, rt.config);
+ * expect(blocks.some((c) => c.name === "Button")).toBe(true);
+ * rt.dispose();
+ *
+ * @example
+ * const rt = await createTestRuntime({ config: "filtered-config.json" });
+ * expect(rt.config.tier).toBe("apps/lxd");
+ * rt.dispose();
+ *
+ * @note Impure
+ */
+export default async function createTestRuntime(options?: {
+  config?: ConfigName;
+}): Promise<PragmaRuntime> {
+  const configFile = options?.config ?? "canonical-config.json";
+
+  // Stage a temp directory with pragma.config.json so bootPragma's
+  // readConfig() finds it via the real config lookup path.
+  const tmpDir = mkdtempSync(join(tmpdir(), "pragma-test-"));
+  copyFileSync(
+    join(FIXTURES_DIR, configFile),
+    join(tmpDir, "pragma.config.json"),
+  );
+
+  const runtime = await bootPragma({
+    cwd: tmpDir,
+    sources: [CANONICAL_TTL],
+  });
+
+  // Wrap dispose to also clean up the temp directory.
+  const originalDispose = runtime.dispose.bind(runtime);
+  return {
+    ...runtime,
+    dispose: () => {
+      originalDispose();
+      rmSync(tmpDir, { recursive: true, force: true });
+    },
+  };
+}

package/src/testing/index.ts

@@ -0,0 +1,8 @@
+/** @module Test infrastructure: CLI subprocess runner, MCP test client, fixtures, and test store factory. */
+export type { CommandResult } from "./cli.js";
+export { runCommand } from "./cli.js";
+export { default as createTestMcpClient } from "./createTestMcpClient.js";
+export { DS_ALL_TTL, DS_ONTOLOGY_TTL, DS_TIERS_TTL } from "./dsFixtures.js";
+export type { PragmaTestStoreOptions } from "./store.js";
+export { createTestStore } from "./store.js";
+export type { TestMcpClientResult } from "./types.js";