@canonical/pragma-cli 0.30.0 → 0.31.0

package/src/testing/dsFixtures.ts

@@ -5,16 +5,19 @@
  * that D3 operations query against.
  *
  * All @prefix declarations derived from {@link TTL_PREFIXES} so that
- * a namespace rename in PREFIX_MAP propagates here automatically.
+ * a namespace rename in DEFAULT_PREFIX_MAP propagates here automatically.
  */
 
-import { PREFIX_MAP, TTL_PREFIXES } from "../domains/shared/prefixes.js";
+import {
+  DEFAULT_PREFIX_MAP,
+  TTL_PREFIXES,
+} from "../domains/shared/prefixes.js";
 
 /** Turtle @prefix block for ds: only (most data fixtures). */
-const dsPrefix = `@prefix ds: <${PREFIX_MAP.ds}> .`;
+const dsPrefix = `@prefix ds: <${DEFAULT_PREFIX_MAP.ds}> .`;
 
 /** Turtle @prefix block for cs: only (standards fixtures). */
-const csPrefix = `@prefix cs: <${PREFIX_MAP.cs}> .`;
+const csPrefix = `@prefix cs: <${DEFAULT_PREFIX_MAP.cs}> .`;
 
 // =============================================================================
 // Ontology (TBox) — class and property definitions
@@ -225,6 +228,20 @@ cs:code a owl:DatatypeProperty ;
 cs:extends a owl:ObjectProperty ;
   rdfs:domain cs:CodeStandard ;
   rdfs:range cs:CodeStandard .
+
+# ---- TBox extras (header, comments, functional typing, SHACL) ----
+
+ds:ontology a owl:Ontology ;
+  rdfs:label "Design System Ontology" ;
+  owl:versionInfo "0.1.0-test" .
+
+ds:Component rdfs:comment "A reusable UI building block." .
+
+ds:tier a owl:FunctionalProperty .
+
+ds:ComponentShape a <http://www.w3.org/ns/shacl#NodeShape> ;
+  <http://www.w3.org/ns/shacl#targetClass> ds:Component ;
+  <http://www.w3.org/ns/shacl#property> ds:shapeName, ds:shapeTier .
 `;
 
 // =============================================================================

package/src/testing/index.ts

@@ -10,10 +10,7 @@ export {
   GRAPHQL_ERROR_TTL,
   GRAPHQL_FATAL_TTL,
 } from "./graphqlFixtures.js";
-export {
-  PARITY_GAPS,
-  STANDARD_PACK_STORY,
-} from "./standardParityFixtures.js";
+export { PARITY_GAPS } from "./standardParityFixtures.js";
 export type { PragmaTestStoreOptions } from "./store.js";
 export { createTestStore } from "./store.js";
 export {

package/src/testing/integration/__snapshots__/executor-golden.test.ts.snap

@@ -1182,9 +1182,9 @@ No changes were made."
 exports[`golden: runSetupTask — setups > lsp — dry-run 1`] = `
 "Dry run — the following operations would be performed:
 
-├─ Info          Installing Terrazzo LSP extension for VS Code...
+├─ Info          Ensuring the Terrazzo LSP VS Code extension is installed...
 ├─ Execute       bunx @canonical/terrazzo-lsp-extension
-└─ Info          ✓ Terrazzo LSP extension installed.
+└─ Info          ✓ Terrazzo LSP extension is installed (up to date).
 
 No changes were made."
 `;
@@ -1193,14 +1193,14 @@ exports[`golden: runSetupTask — setups > lsp — dry-run json 1`] = `
 "[
   {
     "action": "Log",
-    "message": "Installing Terrazzo LSP extension for VS Code..."
+    "message": "Ensuring the Terrazzo LSP VS Code extension is installed..."
   },
   {
     "action": "Exec"
   },
   {
     "action": "Log",
-    "message": "✓ Terrazzo LSP extension installed."
+    "message": "✓ Terrazzo LSP extension is installed (up to date)."
   }
 ]
 "

package/src/testing/integration/cli-user-stories.test.ts

@@ -52,6 +52,30 @@ function parseJson<T>(result: CommandResult): T {
 }
 
 describe("CLI user stories", () => {
+  it("story: a first-time user is greeted once and gets a global config", () => {
+    const workspace = createWorkspace();
+    const freshXdg = mkdtempSync(join(tmpdir(), "pragma-firstrun-e2e-"));
+    tempDirs.add(freshXdg);
+    const env = { XDG_CONFIG_HOME: freshXdg };
+
+    // First invocation: greeting on stderr, config created, stdout untouched.
+    const first = runCommand(["info", "--format", "json"], workspace, env);
+    expect(first.exitCode).toBe(0);
+    expect(first.stderr).toContain("pre-release pragma CLI");
+    expect(first.stderr).toContain(join(freshXdg, "pragma", "config.json"));
+    expect(() => JSON.parse(first.stdout)).not.toThrow();
+    expect(
+      JSON.parse(
+        readFileSync(join(freshXdg, "pragma", "config.json"), "utf-8"),
+      ),
+    ).toEqual({});
+
+    // Second invocation: no greeting — first-run happens once.
+    const second = runCommand(["info", "--format", "json"], workspace, env);
+    expect(second.exitCode).toBe(0);
+    expect(second.stderr.trim()).toBe("");
+  }, 40_000);
+
   it("story: a new contributor verifies the local installation with info", () => {
     const workspace = createWorkspace();
 
@@ -195,4 +219,43 @@ describe("CLI user stories", () => {
     expect(existsSync(indexFile)).toBe(true);
     expect(readFileSync(indexFile, "utf-8")).toContain("./MySth");
   }, 20_000);
+
+  it("story: --version works at the root, noun, and verb levels", () => {
+    const workspace = createWorkspace();
+    const root = runCommand(["--version"], workspace);
+    const verb = runCommand(["block", "list", "--version"], workspace);
+
+    expectSuccess(root);
+    expectSuccess(verb);
+    expect(root.stdout.trim()).toBe(verb.stdout.trim());
+    expect(root.stdout.trim()).toMatch(/^\d+\.\d+\.\d+/);
+  }, 20_000);
+
+  it("story: an unknown verb under a known noun lists that noun's verbs", () => {
+    const workspace = createWorkspace();
+
+    const result = runCommand(["standard", "frobnicate"], workspace);
+
+    expect(result.exitCode).not.toBe(0);
+    // Errors, then defers to the category that exists.
+    expect(result.stderr).toContain("unknown command 'frobnicate'");
+    expect(result.stderr).toContain("pragma standard <verb>");
+    expect(result.stderr).toContain("list");
+    expect(result.stderr).toContain("lookup");
+  }, 20_000);
+
+  it("story: a global flag before the noun still lists that noun's verbs", () => {
+    const workspace = createWorkspace();
+
+    // `--format json` sits before the noun; the flag *value* (`json`) must not
+    // be mistaken for the noun, or no verbs would be suggested.
+    const result = runCommand(
+      ["--format", "json", "standard", "frobnicate"],
+      workspace,
+    );
+
+    expect(result.exitCode).not.toBe(0);
+    expect(result.stderr).toContain("pragma standard <verb>");
+    expect(result.stderr).toContain("lookup");
+  }, 20_000);
 });

package/src/testing/integration/cross-binary-byte-equality.test.ts

@@ -27,10 +27,10 @@ import {
   executeGenerator,
   runGeneratorTask,
 } from "@canonical/cli-core";
+import { generators as componentGenerators } from "@canonical/summon-component";
 import type { GeneratorDefinition } from "@canonical/summon-core";
 import { generators as packageGenerators } from "@canonical/summon-package";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { COMPONENT_GENERATORS } from "../../domains/create/generators.js";
 
 interface Case {
   readonly name: string;
@@ -41,7 +41,7 @@ interface Case {
 const cases: Case[] = [
   {
     name: "component/react",
-    gen: COMPONENT_GENERATORS.react as GeneratorDefinition,
+    gen: componentGenerators["component/react"] as GeneratorDefinition,
     answers: { componentPath: "src/components/Button" },
   },
   {

package/src/testing/integration/edge-cases.test.ts

@@ -10,6 +10,7 @@
 import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import type { PragmaRuntime } from "../../domains/shared/runtime.js";
+import { TOKEN_READ_SURFACE_ENABLED } from "../../domains/token/featureFlag.js";
 import createTestMcpClient from "../helpers/createTestMcpClient.js";
 import createTestRuntime from "../helpers/createTestRuntime.js";
 
@@ -122,21 +123,24 @@ describe("all-fail batch lookups", () => {
     expect(data.errors[0]?.code).toBe("ENTITY_NOT_FOUND");
   });
 
-  it("token_lookup: unknown token → error", async () => {
-    const res = await client.callTool({
-      name: "token_lookup",
-      arguments: { names: ["color.nonexistent"] },
-    });
-    const body = parseEnvelope(res);
-    expect(body.ok).toBe(true);
-    const data = body.data as {
-      results: unknown[];
-      errors: { query: string; code: string }[];
-    };
-    expect(data.results).toHaveLength(0);
-    expect(data.errors).toHaveLength(1);
-    expect(data.errors[0]?.code).toBe("ENTITY_NOT_FOUND");
-  });
+  it.skipIf(!TOKEN_READ_SURFACE_ENABLED)(
+    "token_lookup: unknown token → error",
+    async () => {
+      const res = await client.callTool({
+        name: "token_lookup",
+        arguments: { names: ["color.nonexistent"] },
+      });
+      const body = parseEnvelope(res);
+      expect(body.ok).toBe(true);
+      const data = body.data as {
+        results: unknown[];
+        errors: { query: string; code: string }[];
+      };
+      expect(data.results).toHaveLength(0);
+      expect(data.errors).toHaveLength(1);
+      expect(data.errors[0]?.code).toBe("ENTITY_NOT_FOUND");
+    },
+  );
 });
 
 // ---------------------------------------------------------------------------
@@ -144,33 +148,38 @@ describe("all-fail batch lookups", () => {
 // ---------------------------------------------------------------------------
 
 describe("empty result sets", () => {
-  it("standard_list with nonexistent category → error envelope", async () => {
+  it("standard_list with nonexistent category → empty rows", async () => {
     const res = await client.callTool({
       name: "standard_list",
       arguments: { category: "nonexistent_category" },
     });
     const body = parseEnvelope(res);
-    // resolveStandardList throws when no results found
-    expect(body.ok).toBe(false);
-    const error = body.error as { code: string };
-    expect(error.code).toBeDefined();
+    // The bundled pack's value-free category filter returns zero rows for
+    // an unmatched value; the old EMPTY_RESULTS error is a pinned
+    // PARITY_GAP of the standard cutover (packs have no emptyError hook).
+    expect(body.ok).toBe(true);
+    expect(body.data).toEqual([]);
+    expect((body.meta as { count: number }).count).toBe(0);
   });
 
-  it("token_list with nonexistent category → empty or error", async () => {
-    const res = await client.callTool({
-      name: "token_list",
-      arguments: { category: "NonexistentType" },
-    });
-    const body = parseEnvelope(res);
-    if (body.ok) {
-      const data = body.data as unknown[];
-      expect(data).toHaveLength(0);
-    } else {
-      // Token list may throw on empty results
-      const error = body.error as { code: string };
-      expect(error.code).toBeDefined();
-    }
-  });
+  it.skipIf(!TOKEN_READ_SURFACE_ENABLED)(
+    "token_list with nonexistent category → empty or error",
+    async () => {
+      const res = await client.callTool({
+        name: "token_list",
+        arguments: { category: "NonexistentType" },
+      });
+      const body = parseEnvelope(res);
+      if (body.ok) {
+        const data = body.data as unknown[];
+        expect(data).toHaveLength(0);
+      } else {
+        // Token list may throw on empty results
+        const error = body.error as { code: string };
+        expect(error.code).toBeDefined();
+      }
+    },
+  );
 });
 
 // ---------------------------------------------------------------------------
@@ -245,19 +254,22 @@ describe("condensed mode error rendering", () => {
     expect(text).toContain("nonexistent");
   });
 
-  it("token_lookup condensed: includes error for unknown token", async () => {
-    const res = await client.callTool({
-      name: "token_lookup",
-      arguments: {
-        names: ["color.primary", "color.nonexistent"],
-        condensed: true,
-      },
-    });
-    const body = parseEnvelope(res);
-    expect(body.condensed).toBe(true);
-    const text = body.text as string;
-    expect(text).toContain("color.primary");
-    expect(text).toContain("Errors");
-    expect(text).toContain("color.nonexistent");
-  });
+  it.skipIf(!TOKEN_READ_SURFACE_ENABLED)(
+    "token_lookup condensed: includes error for unknown token",
+    async () => {
+      const res = await client.callTool({
+        name: "token_lookup",
+        arguments: {
+          names: ["color.primary", "color.nonexistent"],
+          condensed: true,
+        },
+      });
+      const body = parseEnvelope(res);
+      expect(body.condensed).toBe(true);
+      const text = body.text as string;
+      expect(text).toContain("color.primary");
+      expect(text).toContain("Errors");
+      expect(text).toContain("color.nonexistent");
+    },
+  );
 });

package/src/testing/integration/executor-execution.test.ts

@@ -20,10 +20,10 @@ import {
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { runGeneratorTask } from "@canonical/cli-core";
+import { generators as componentGenerators } from "@canonical/summon-component";
 import { generators as packageGenerators } from "@canonical/summon-package";
 import type { Task } from "@canonical/task";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { COMPONENT_GENERATORS } from "../../domains/create/generators.js";
 import setupMcp from "../../domains/setup/operations/setupMcp.js";
 
 interface Case {
@@ -37,15 +37,17 @@ const packageParams = { name: "@canonical/example", type: "library" };
 const cases: Case[] = [
   {
     name: "component/react",
-    build: () => COMPONENT_GENERATORS.react.generate(componentParams),
+    build: () =>
+      componentGenerators["component/react"].generate(componentParams),
   },
   {
     name: "component/svelte",
-    build: () => COMPONENT_GENERATORS.svelte.generate(componentParams),
+    build: () =>
+      componentGenerators["component/svelte"].generate(componentParams),
   },
   {
     name: "component/lit",
-    build: () => COMPONENT_GENERATORS.lit.generate(componentParams),
+    build: () => componentGenerators["component/lit"].generate(componentParams),
   },
   {
     name: "package/library",

package/src/testing/integration/executor-golden.test.ts

@@ -16,9 +16,9 @@ import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { CommandContext, CommandResult } from "@canonical/cli-core";
 import { executeGenerator } from "@canonical/cli-core";
+import { generators as componentGenerators } from "@canonical/summon-component";
 import { generators as packageGenerators } from "@canonical/summon-package";
 import { describe, expect, it } from "vitest";
-import { COMPONENT_GENERATORS } from "../../domains/create/generators.js";
 import runSetupTask from "../../domains/setup/helpers/runSetupTask.js";
 import setupCompletions from "../../domains/setup/operations/setupCompletions.js";
 import setupLsp from "../../domains/setup/operations/setupLsp.js";
@@ -65,7 +65,7 @@ const packageParams = { name: "@canonical/example", type: "library" };
 
 describe("golden: executeGenerator — components", () => {
   for (const framework of ["react", "svelte", "lit"] as const) {
-    const gen = COMPONENT_GENERATORS[framework];
+    const gen = componentGenerators[`component/${framework}`];
 
     it(`${framework} — dry-run plan`, async () => {
       const result = await executeGenerator(

package/src/testing/integration/mcp-surface.test.ts

@@ -9,6 +9,7 @@
 import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import type { PragmaRuntime } from "../../domains/shared/runtime.js";
+import { TOKEN_READ_SURFACE_ENABLED } from "../../domains/token/featureFlag.js";
 import createTestMcpClient from "../helpers/createTestMcpClient.js";
 import createTestRuntime from "../helpers/createTestRuntime.js";
 
@@ -55,7 +56,7 @@ describe("capabilities", () => {
     expect(toolNames).toContain("block_list");
     expect(toolNames).toContain("capabilities");
     expect(data.tools.every((t) => t.use_when.length > 0)).toBe(true);
-    expect(data.counts.total).toBe(30);
+    expect(data.counts.total).toBe(TOKEN_READ_SURFACE_ENABLED ? 34 : 31);
     expect(data.conventions).toBeDefined();
     expect(data.version).toBeDefined();
   });
@@ -190,7 +191,11 @@ describe("standard_lookup", () => {
       results: { name: string; extends?: string }[];
     };
     expect(data.results[0]?.name).toBe("react/component/props");
-    expect(data.results[0]?.extends).toBe("cs:react_folder");
+    // Pack entities keep cs:extends as the raw IRI in data (compaction is
+    // display-time only) — a pinned PARITY_GAP of the standard cutover.
+    expect(data.results[0]?.extends).toBe(
+      "http://pragma.canonical.com/codestandards#react_folder",
+    );
   });
 });
 
@@ -240,7 +245,7 @@ describe("modifier_lookup", () => {
 // Token
 // ---------------------------------------------------------------------------
 
-describe("token_list", () => {
+describe.skipIf(!TOKEN_READ_SURFACE_ENABLED)("token_list", () => {
   it("returns tokens", async () => {
     const res = await client.callTool({
       name: "token_list",
@@ -252,7 +257,7 @@ describe("token_list", () => {
   });
 });
 
-describe("token_lookup", () => {
+describe.skipIf(!TOKEN_READ_SURFACE_ENABLED)("token_lookup", () => {
   it("returns token with values", async () => {
     const res = await client.callTool({
       name: "token_lookup",
@@ -273,15 +278,16 @@ describe("token_lookup", () => {
 // ---------------------------------------------------------------------------
 
 describe("tier_list", () => {
-  it("returns tiers with hierarchy", async () => {
+  it("returns the tiers (bundled pack)", async () => {
     const res = await client.callTool({
       name: "tier_list",
       arguments: {},
     });
     const body = parseEnvelope(res);
     expect(body.ok).toBe(true);
-    const data = body.data as { path: string }[];
-    expect(data.some((t) => t.path === "global")).toBe(true);
+    // Bundled tier pack: uniform `{uri, name}` rows (no bespoke hierarchy).
+    const data = body.data as { name: string }[];
+    expect(data.some((t) => t.name === "global")).toBe(true);
   });
 });
 
@@ -480,15 +486,34 @@ describe("disclosure", () => {
     expect(meta.disclosure).toBe("digest");
   });
 
-  it("standard_list with detailed returns enriched data", async () => {
-    const res = await client.callTool({
-      name: "standard_list",
-      arguments: { detailed: true },
+  // `standard list --detailed` was retired with the standard cutover (a
+  // pinned PARITY_GAP: pack lists are single-level); per-entity disclosure
+  // now lives on the lookup's `detail` parameter and its legacy aliases.
+  it("standard_lookup honors the detail parameter", async () => {
+    const summary = await client.callTool({
+      name: "standard_lookup",
+      arguments: {
+        names: ["react/component/folder-structure"],
+        detail: "summary",
+      },
     });
-    const body = parseEnvelope(res);
-    expect(body.ok).toBe(true);
-    const meta = body.meta as { disclosure?: string };
-    expect(meta.disclosure).toBe("detailed");
+    const summaryData = parseEnvelope(summary).data as {
+      results: Record<string, unknown>[];
+    };
+    expect(summaryData.results[0]).not.toHaveProperty("dos");
+
+    const detailed = await client.callTool({
+      name: "standard_lookup",
+      arguments: {
+        names: ["react/component/folder-structure"],
+        detail: "detailed",
+      },
+    });
+    const detailedData = parseEnvelope(detailed).data as {
+      results: Record<string, unknown>[];
+    };
+    expect(detailedData.results[0]).toHaveProperty("dos");
+    expect(detailedData.results[0]).toHaveProperty("donts");
   });
 });