@canonical/pragma-cli 0.24.0 → 0.26.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@canonical/pragma-cli",
   "description": "CLI and MCP server for Canonical's design system.",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "type": "module",
   "module": "src/index.ts",
   "types": "src/index.ts",
@@ -57,9 +57,9 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.9",
-    "@canonical/biome-config": "^0.24.0",
-    "@canonical/typescript-config": "^0.24.0",
-    "@canonical/webarchitect": "^0.24.0",
+    "@canonical/biome-config": "^0.26.0",
+    "@canonical/typescript-config": "^0.26.0",
+    "@canonical/webarchitect": "^0.26.0",
     "@types/bun": "^1.3.10",
     "@types/node": "^24.12.0",
     "@types/react": "^19.2.14",
@@ -73,13 +73,13 @@
     "@canonical/design-system": "^0.1.2"
   },
   "dependencies": {
-    "@canonical/cli-core": "^0.24.0",
-    "@canonical/harnesses": "^0.24.0",
-    "@canonical/ke": "^0.24.0",
-    "@canonical/summon-component": "^0.24.0",
-    "@canonical/summon-core": "^0.24.0",
-    "@canonical/summon-package": "^0.24.0",
-    "@canonical/task": "^0.24.0",
+    "@canonical/cli-core": "^0.26.0",
+    "@canonical/harnesses": "^0.26.0",
+    "@canonical/ke": "^0.26.0",
+    "@canonical/summon-component": "^0.26.0",
+    "@canonical/summon-core": "^0.26.0",
+    "@canonical/summon-package": "^0.26.0",
+    "@canonical/task": "^0.26.0",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
@@ -88,5 +88,5 @@
     "react": "^19.2.4",
     "zod": "^3.25.0"
   },
-  "gitHead": "28565e3591ad80525b62bd7be6343d1f12ebf4d0"
+  "gitHead": "55fece1380dba8dcd3a88af443dd509d9aaaccb2"
 }

package/src/config/readConfig.test.ts

@@ -73,6 +73,105 @@ describe("readConfig", () => {
     const config = readConfig(dir);
     expect(config.tier).toBeUndefined();
   });
+
+  describe("packages field", () => {
+    it("parses string-only packages array", () => {
+      writeFileSync(
+        join(dir, "pragma.config.json"),
+        JSON.stringify({
+          packages: ["@canonical/design-system", "@canonical/code-standards"],
+        }),
+      );
+      const config = readConfig(dir);
+      expect(config.packages).toEqual([
+        "@canonical/design-system",
+        "@canonical/code-standards",
+      ]);
+    });
+
+    it("parses mixed string and object packages", () => {
+      writeFileSync(
+        join(dir, "pragma.config.json"),
+        JSON.stringify({
+          packages: [
+            "@canonical/design-system",
+            {
+              name: "@canonical/code-standards",
+              source: "file:///home/user/code/code-standards",
+            },
+          ],
+        }),
+      );
+      const config = readConfig(dir);
+      expect(config.packages).toEqual([
+        "@canonical/design-system",
+        {
+          name: "@canonical/code-standards",
+          source: "file:///home/user/code/code-standards",
+        },
+      ]);
+    });
+
+    it("parses object without source as npm", () => {
+      writeFileSync(
+        join(dir, "pragma.config.json"),
+        JSON.stringify({
+          packages: [{ name: "@canonical/design-system" }],
+        }),
+      );
+      const config = readConfig(dir);
+      expect(config.packages).toEqual([{ name: "@canonical/design-system" }]);
+    });
+
+    it("returns no packages field when absent", () => {
+      writeFileSync(join(dir, "pragma.config.json"), '{"tier":"global"}');
+      const config = readConfig(dir);
+      expect(config.packages).toBeUndefined();
+    });
+
+    it("throws on non-array packages", () => {
+      writeFileSync(
+        join(dir, "pragma.config.json"),
+        '{"packages":"not-an-array"}',
+      );
+      expect(() => readConfig(dir)).toThrow(PragmaError);
+    });
+
+    it("throws on object entry with empty name", () => {
+      writeFileSync(
+        join(dir, "pragma.config.json"),
+        JSON.stringify({ packages: [{ name: "" }] }),
+      );
+      expect(() => readConfig(dir)).toThrow(PragmaError);
+    });
+
+    it("throws on invalid source scheme", () => {
+      writeFileSync(
+        join(dir, "pragma.config.json"),
+        JSON.stringify({
+          packages: [
+            { name: "@canonical/ds", source: "https://example.com/foo.tar.gz" },
+          ],
+        }),
+      );
+      expect(() => readConfig(dir)).toThrow(PragmaError);
+    });
+
+    it("throws on git source without ref", () => {
+      writeFileSync(
+        join(dir, "pragma.config.json"),
+        JSON.stringify({
+          packages: [
+            {
+              name: "@canonical/ds",
+              source: "git+https://github.com/canonical/ds.git",
+            },
+          ],
+        }),
+      );
+      expect(() => readConfig(dir)).toThrow(PragmaError);
+    });
+  });
 });
 
 describe("writeConfig", () => {
@@ -149,4 +248,57 @@ describe("writeConfig", () => {
     writeFileSync(join(dir, "pragma.config.json"), "{invalid json");
     expect(() => writeConfig(dir, { tier: "apps" })).toThrow();
   });
+
+  describe("packages field", () => {
+    it("writes packages array", () => {
+      writeConfig(dir, {
+        packages: [
+          "@canonical/design-system",
+          {
+            name: "@canonical/code-standards",
+            source: "file:///home/user/code/code-standards",
+          },
+        ],
+      });
+      const config = readConfig(dir);
+      expect(config.packages).toEqual([
+        "@canonical/design-system",
+        {
+          name: "@canonical/code-standards",
+          source: "file:///home/user/code/code-standards",
+        },
+      ]);
+    });
+
+    it("merges packages into existing config without touching tier", () => {
+      writeFileSync(join(dir, "pragma.config.json"), '{"tier":"global"}');
+      writeConfig(dir, { packages: ["@canonical/design-system"] });
+      const config = readConfig(dir);
+      expect(config.tier).toBe("global");
+      expect(config.packages).toEqual(["@canonical/design-system"]);
+    });
+
+    it("removes packages when set to undefined", () => {
+      writeFileSync(
+        join(dir, "pragma.config.json"),
+        JSON.stringify({ packages: ["@canonical/design-system"] }),
+      );
+      writeConfig(dir, { packages: undefined });
+      const config = readConfig(dir);
+      expect(config.packages).toBeUndefined();
+    });
+
+    it("round-trips packages through write then read", () => {
+      const packages = [
+        "@canonical/design-system",
+        {
+          name: "@canonical/anatomy-dsl",
+          source: "git+https://github.com/canonical/anatomy-dsl.git#main",
+        },
+      ];
+      writeConfig(dir, { packages });
+      const config = readConfig(dir);
+      expect(config.packages).toEqual(packages);
+    });
+  });
 });

package/src/config/readConfig.ts

@@ -1,5 +1,9 @@
 import { readFileSync } from "node:fs";
 import { type Channel, VALID_CHANNELS } from "../constants.js";
+import {
+  parsePackageEntry,
+  type RawPackageEntry,
+} from "../domains/refs/operations/parseRef.js";
 import { PragmaError } from "../error/PragmaError.js";
 import resolveConfigPath from "./resolveConfigPath.js";
 import type { PragmaConfig } from "./types.js";
@@ -60,5 +64,63 @@ export default function readConfig(cwd: string = process.cwd()): PragmaConfig {
     channel = parsed.channel;
   }
 
-  return { tier, channel };
+  const packages = parsePackagesField(parsed.packages);
+
+  return packages ? { tier, channel, packages } : { tier, channel };
+}
+
+// ---------------------------------------------------------------------------
+// Packages field parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate and parse the `packages` config field.
+ *
+ * @returns The validated array, or `undefined` when the field is absent.
+ * @throws PragmaError if the field is present but malformed.
+ */
+function parsePackagesField(
+  raw: unknown,
+): ReadonlyArray<RawPackageEntry> | undefined {
+  if (raw === undefined || raw === null) return undefined;
+
+  if (!Array.isArray(raw)) {
+    throw PragmaError.configError(
+      '"packages" must be an array of strings or { name, source? } objects.',
+    );
+  }
+
+  const entries: RawPackageEntry[] = [];
+  for (const item of raw) {
+    if (typeof item === "string") {
+      entries.push(item);
+      continue;
+    }
+    if (typeof item === "object" && item !== null && !Array.isArray(item)) {
+      const obj = item as Record<string, unknown>;
+      if (typeof obj.name !== "string" || obj.name.length === 0) {
+        throw PragmaError.configError(
+          'Each object in "packages" must have a non-empty "name" string.',
+        );
+      }
+      const entry: { name: string; source?: string } = { name: obj.name };
+      if (obj.source !== undefined) {
+        if (typeof obj.source !== "string") {
+          throw PragmaError.configError(
+            `Invalid source for "${obj.name}": expected a string.`,
+          );
+        }
+        entry.source = obj.source;
+      }
+      // Validate format eagerly — fail fast on bad config
+      parsePackageEntry(entry);
+      entries.push(entry);
+      continue;
+    }
+    throw PragmaError.configError(
+      'Each entry in "packages" must be a string or { name, source? } object.',
+    );
+  }
+
+  return entries;
 }

package/src/config/types.ts

@@ -6,6 +6,7 @@
  */
 
 import type { Channel } from "../constants.js";
+import type { RawPackageEntry } from "../domains/refs/operations/parseRef.js";
 
 /** Parsed contents of pragma.config.json. */
 interface PragmaConfig {
@@ -13,6 +14,12 @@ interface PragmaConfig {
   tier: string | undefined;
   /** Release channel controlling component visibility. */
   channel: Channel;
+  /**
+   * Semantic package sources. Each entry is a package name (npm) or an
+   * object with `{ name, source }` where source is `file://` or `git+https://`.
+   * When absent, the hardcoded defaults are used.
+   */
+  packages?: ReadonlyArray<RawPackageEntry> | undefined;
 }
 
 /** Partial update payload for writing config changes. */
@@ -21,6 +28,8 @@ interface ConfigUpdate {
   tier?: string | undefined;
   /** New channel, `undefined` to remove the channel field. */
   channel?: Channel | undefined;
+  /** New packages list, `undefined` to remove the field. */
+  packages?: ReadonlyArray<RawPackageEntry> | undefined;
 }
 
 export type { ConfigUpdate, PragmaConfig };

package/src/config/writeConfig.ts

@@ -44,6 +44,12 @@ export default function writeConfig(cwd: string, update: ConfigUpdate): void {
     delete existing.channel;
   }
 
+  if (update.packages !== undefined) {
+    existing.packages = update.packages;
+  } else if ("packages" in update) {
+    delete existing.packages;
+  }
+
   writeFileSync(tempPath, `${JSON.stringify(existing, null, 2)}\n`);
   renameSync(tempPath, configPath);
 }

package/src/domains/doctor/operations/checks/checkPackageRefs.ts

@@ -0,0 +1,76 @@
+/**
+ * Doctor check: report how each semantic package is resolved.
+ *
+ * Shows whether packages resolve from npm, file://, or git cache,
+ * and warns if a configured ref is missing its cache.
+ */
+
+import { existsSync } from "node:fs";
+import { readConfig } from "#config";
+import {
+  parsePackageEntry,
+  type RawPackageEntry,
+} from "../../../refs/operations/parseRef.js";
+import { gitCacheDir } from "../../../refs/operations/paths.js";
+import readGlobalRefs from "../../../refs/operations/readGlobalRefs.js";
+import { DEFAULT_PACKAGES } from "../../../shared/packages.js";
+import type { CheckContext, CheckResult } from "../types.js";
+
+export default async function checkPackageRefs(
+  ctx: CheckContext,
+): Promise<CheckResult> {
+  const config = readConfig(ctx.cwd);
+  const globalEntries = readGlobalRefs();
+
+  const hasProjectRefs = config.packages && config.packages.length > 0;
+  const hasGlobalRefs = globalEntries.length > 0;
+
+  if (!hasProjectRefs && !hasGlobalRefs) {
+    return {
+      name: "package refs",
+      status: "pass",
+      detail: `${DEFAULT_PACKAGES.length} packages (all npm, defaults)`,
+    };
+  }
+
+  const entries: ReadonlyArray<RawPackageEntry> =
+    config.packages ?? globalEntries;
+
+  const details: string[] = [];
+  let hasIssue = false;
+
+  for (const entry of entries) {
+    const ref = parsePackageEntry(entry);
+
+    switch (ref.kind) {
+      case "npm":
+        details.push(`${ref.pkg}: npm`);
+        break;
+      case "file":
+        if (existsSync(ref.path)) {
+          details.push(`${ref.pkg}: file (${ref.path})`);
+        } else {
+          details.push(`${ref.pkg}: file MISSING (${ref.path})`);
+          hasIssue = true;
+        }
+        break;
+      case "git": {
+        const cached = existsSync(gitCacheDir(ref.pkg, ref.ref));
+        if (cached) {
+          details.push(`${ref.pkg}: git #${ref.ref} (cached)`);
+        } else {
+          details.push(`${ref.pkg}: git #${ref.ref} NOT CACHED`);
+          hasIssue = true;
+        }
+        break;
+      }
+    }
+  }
+
+  return {
+    name: "package refs",
+    status: hasIssue ? "fail" : "pass",
+    detail: details.join("; "),
+    ...(hasIssue ? { remedy: "pragma update-refs" } : {}),
+  };
+}

package/src/domains/doctor/operations/checks/index.ts

@@ -3,6 +3,7 @@ export { default as checkConfigFile } from "./checkConfigFile.js";
 export { default as checkKeStore } from "./checkKeStore.js";
 export { default as checkMcpConfigured } from "./checkMcpConfigured.js";
 export { default as checkNodeVersion } from "./checkNodeVersion.js";
+export { default as checkPackageRefs } from "./checkPackageRefs.js";
 export { default as checkPragmaVersion } from "./checkPragmaVersion.js";
 export { default as checkShellCompletions } from "./checkShellCompletions.js";
 export { default as checkSkillsSymlinked } from "./checkSkillsSymlinked.js";

package/src/domains/doctor/operations/runChecks.test.ts

@@ -4,6 +4,7 @@ vi.mock("./checks/index.js", () => ({
   checkNodeVersion: vi.fn(),
   checkPragmaVersion: vi.fn(),
   checkConfigFile: vi.fn(),
+  checkPackageRefs: vi.fn(),
   checkKeStore: vi.fn(),
   checkShellCompletions: vi.fn(),
   checkMcpConfigured: vi.fn(),
@@ -15,6 +16,7 @@ import {
   checkKeStore,
   checkMcpConfigured,
   checkNodeVersion,
+  checkPackageRefs,
   checkPragmaVersion,
   checkShellCompletions,
   checkSkillsSymlinked,
@@ -43,29 +45,31 @@ describe("runChecks", () => {
     vi.mocked(checkNodeVersion).mockResolvedValue(pass("Node"));
     vi.mocked(checkPragmaVersion).mockResolvedValue(pass("pragma"));
     vi.mocked(checkConfigFile).mockResolvedValue(pass("config"));
+    vi.mocked(checkPackageRefs).mockResolvedValue(pass("refs"));
     vi.mocked(checkKeStore).mockResolvedValue(pass("store"));
     vi.mocked(checkShellCompletions).mockResolvedValue(pass("completions"));
     vi.mocked(checkMcpConfigured).mockResolvedValue(pass("mcp"));
     vi.mocked(checkSkillsSymlinked).mockResolvedValue(pass("skills"));
 
     const data = await runChecks({ cwd: "/test" });
-    expect(data.passed).toBe(7);
+    expect(data.passed).toBe(8);
     expect(data.failed).toBe(0);
     expect(data.skipped).toBe(0);
-    expect(data.checks).toHaveLength(7);
+    expect(data.checks).toHaveLength(8);
   });
 
   it("counts failures and skips correctly", async () => {
     vi.mocked(checkNodeVersion).mockResolvedValue(pass("Node"));
     vi.mocked(checkPragmaVersion).mockResolvedValue(pass("pragma"));
     vi.mocked(checkConfigFile).mockResolvedValue(fail("config"));
+    vi.mocked(checkPackageRefs).mockResolvedValue(pass("refs"));
     vi.mocked(checkKeStore).mockResolvedValue(fail("store"));
     vi.mocked(checkShellCompletions).mockResolvedValue(fail("completions"));
     vi.mocked(checkMcpConfigured).mockResolvedValue(pass("mcp"));
     vi.mocked(checkSkillsSymlinked).mockResolvedValue(skip("skills"));
 
     const data = await runChecks({ cwd: "/test" });
-    expect(data.passed).toBe(3);
+    expect(data.passed).toBe(4);
     expect(data.failed).toBe(3);
     expect(data.skipped).toBe(1);
   });
@@ -74,6 +78,7 @@ describe("runChecks", () => {
     vi.mocked(checkNodeVersion).mockResolvedValue(pass("Node"));
     vi.mocked(checkPragmaVersion).mockResolvedValue(pass("pragma"));
     vi.mocked(checkConfigFile).mockResolvedValue(pass("config"));
+    vi.mocked(checkPackageRefs).mockResolvedValue(pass("refs"));
     vi.mocked(checkKeStore).mockResolvedValue(pass("store"));
     vi.mocked(checkShellCompletions).mockResolvedValue(pass("completions"));
     vi.mocked(checkMcpConfigured).mockResolvedValue(pass("mcp"));
@@ -83,7 +88,8 @@ describe("runChecks", () => {
     expect(data.checks[0].name).toBe("Node");
     expect(data.checks[1].name).toBe("pragma");
     expect(data.checks[2].name).toBe("config");
-    expect(data.checks[3].name).toBe("store");
-    expect(data.checks[6].name).toBe("skills");
+    expect(data.checks[3].name).toBe("refs");
+    expect(data.checks[4].name).toBe("store");
+    expect(data.checks[7].name).toBe("skills");
   });
 });

package/src/domains/doctor/operations/runChecks.ts

@@ -3,6 +3,7 @@ import {
   checkKeStore,
   checkMcpConfigured,
   checkNodeVersion,
+  checkPackageRefs,
   checkPragmaVersion,
   checkShellCompletions,
   checkSkillsSymlinked,
@@ -25,6 +26,7 @@ export default async function runChecks(
   checks.push(await checkNodeVersion());
   checks.push(await checkPragmaVersion());
   checks.push(await checkConfigFile(ctx));
+  checks.push(await checkPackageRefs(ctx));
   checks.push(await checkKeStore(ctx));
   checks.push(await checkShellCompletions());
   checks.push(await checkMcpConfigured(ctx));

package/src/domains/info/formatters/info.test.ts

@@ -98,6 +98,40 @@ describe("renderInfoPlain", () => {
     expect(output).not.toContain("Triples");
     expect(output).not.toContain("Graphs");
   });
+
+  it("includes package refs section", () => {
+    const output = renderInfoPlain(
+      createInfoData({
+        packageRefs: [
+          {
+            pkg: "@canonical/design-system",
+            source: "npm",
+            detail: "node_modules",
+          },
+          {
+            pkg: "@canonical/code-standards",
+            source: "file",
+            detail: "/home/user/code/standards",
+          },
+          {
+            pkg: "@canonical/anatomy-dsl",
+            source: "git",
+            detail: "https://github.com/canonical/anatomy-dsl.git#main",
+          },
+        ],
+      }),
+    );
+    expect(output).toContain("Packages");
+    expect(output).toContain("@canonical/design-system");
+    expect(output).toContain("npm");
+    expect(output).toContain("file");
+    expect(output).toContain("git");
+  });
+
+  it("omits package refs section when absent", () => {
+    const output = renderInfoPlain(createInfoData());
+    expect(output).not.toContain("Packages");
+  });
 });
 
 describe("renderInfoLlm", () => {

package/src/domains/info/formatters/info.ts

@@ -43,6 +43,14 @@ function renderInfoPlain(data: InfoData): string {
     lines.push("  Up to date.");
   }
 
+  if (data.packageRefs && data.packageRefs.length > 0) {
+    lines.push("");
+    lines.push(formatHeading("Packages"));
+    for (const ref of data.packageRefs) {
+      lines.push(formatField(`  ${ref.pkg}:`, `${ref.source} (${ref.detail})`));
+    }
+  }
+
   if (data.store) {
     lines.push("");
     lines.push(formatHeading("Store"));
@@ -93,6 +101,13 @@ function renderInfoLlm(data: InfoData): string {
     lines.push("- Update: up to date");
   }
 
+  if (data.packageRefs && data.packageRefs.length > 0) {
+    lines.push("## Packages");
+    for (const ref of data.packageRefs) {
+      lines.push(`- ${ref.pkg}: ${ref.source} (${ref.detail})`);
+    }
+  }
+
   if (data.store) {
     lines.push(`- Store: ${data.store.tripleCount.toLocaleString()} triples`);
     if (data.store.graphNames.length > 0) {

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

@@ -1,10 +1,16 @@
 import { readConfig } from "#config";
 import { VERSION } from "#constants";
 import { detectInstallSource, PM_COMMANDS } from "#package-manager";
+import {
+  type PackageRef,
+  parsePackageEntry,
+} 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 type { InfoData } from "../types.js";
+import { DEFAULT_PACKAGES } from "../../shared/packages.js";
+import type { InfoData, PackageRefSummary } from "../types.js";
 import checkRegistryVersion from "./checkRegistryVersion.js";
 import { collectStoreSummary } from "./collectStoreSummary.js";
 
@@ -52,6 +58,9 @@ export default async function collectInfo(cwd: string): Promise<InfoData> {
     keStore?.dispose();
   }
 
+  // Collect package ref summaries
+  const packageRefs = collectPackageRefSummaries(config.packages);
+
   return {
     version: VERSION,
     pm,
@@ -64,5 +73,25 @@ export default async function collectInfo(cwd: string): Promise<InfoData> {
     update,
     updateSkipped,
     store,
+    packageRefs,
   };
 }
+
+function collectPackageRefSummaries(
+  projectPackages?: ReadonlyArray<
+    string | { readonly name: string; readonly source?: string }
+  >,
+): PackageRefSummary[] {
+  const entries = projectPackages ?? readGlobalRefs();
+  const raw = entries.length > 0 ? entries : DEFAULT_PACKAGES.map((pkg) => pkg);
+
+  return raw.map((entry) => refToSummary(parsePackageEntry(entry)));
+}
+
+function refToSummary(ref: PackageRef): PackageRefSummary {
+  if (ref.kind === "file")
+    return { pkg: ref.pkg, source: "file", detail: ref.path };
+  if (ref.kind === "git")
+    return { pkg: ref.pkg, source: "git", detail: `${ref.url}#${ref.ref}` };
+  return { pkg: ref.pkg, source: "npm", detail: "node_modules" };
+}

package/src/domains/info/types.ts

@@ -1,3 +1,10 @@
+/** Summary of how a single package is resolved. */
+export interface PackageRefSummary {
+  readonly pkg: string;
+  readonly source: "npm" | "file" | "git";
+  readonly detail: string;
+}
+
 /** Data collected by `pragma info` for rendering. */
 export interface InfoData {
   readonly version: string;
@@ -19,6 +26,7 @@ export interface InfoData {
   readonly store:
     | { readonly tripleCount: number; readonly graphNames: readonly string[] }
     | undefined;
+  readonly packageRefs?: readonly PackageRefSummary[];
 }
 
 /** Data collected by `pragma upgrade` for rendering. */