@canonical/pragma-cli 0.18.0

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

@@ -0,0 +1,133 @@
+import { describe, expect, it } from "vitest";
+import type { UpgradeData } from "../types.js";
+import {
+  renderUpgradeJson,
+  renderUpgradeLlm,
+  renderUpgradePlain,
+} from "./upgrade.js";
+
+function createUpgradeData(overrides: Partial<UpgradeData> = {}): UpgradeData {
+  return {
+    pm: "bun",
+    current: "0.18.0",
+    latest: "0.19.0",
+    command: "bun update -g @canonical/pragma-cli",
+    dryRun: false,
+    alreadyLatest: false,
+    offline: false,
+    executed: true,
+    ...overrides,
+  };
+}
+
+describe("renderUpgradePlain", () => {
+  it("shows PM info", () => {
+    const output = renderUpgradePlain(createUpgradeData());
+    expect(output).toContain("bun (global)");
+  });
+
+  it("shows version transition", () => {
+    const output = renderUpgradePlain(createUpgradeData());
+    expect(output).toContain("0.18.0");
+    expect(output).toContain("0.19.0");
+  });
+
+  it("shows executed message", () => {
+    const output = renderUpgradePlain(createUpgradeData());
+    expect(output).toContain("done. Updated to 0.19.0");
+  });
+
+  it("shows dry-run message", () => {
+    const output = renderUpgradePlain(createUpgradeData({ dryRun: true }));
+    expect(output).toContain("Would run");
+    expect(output).not.toContain("done.");
+  });
+
+  it("shows already latest", () => {
+    const output = renderUpgradePlain(
+      createUpgradeData({ alreadyLatest: true }),
+    );
+    expect(output).toContain("Already at latest version");
+  });
+
+  it("shows offline message", () => {
+    const output = renderUpgradePlain(
+      createUpgradeData({ offline: true, latest: undefined }),
+    );
+    expect(output).toContain("Could not reach registry");
+  });
+
+  it("uses npm command for npm PM", () => {
+    const output = renderUpgradePlain(
+      createUpgradeData({
+        pm: "npm",
+        command: "npm update -g @canonical/pragma-cli",
+      }),
+    );
+    expect(output).toContain("npm update -g @canonical/pragma-cli");
+  });
+
+  it("uses yarn command for yarn PM", () => {
+    const output = renderUpgradePlain(
+      createUpgradeData({
+        pm: "yarn",
+        command: "yarn global upgrade @canonical/pragma-cli",
+      }),
+    );
+    expect(output).toContain("yarn global upgrade @canonical/pragma-cli");
+  });
+});
+
+describe("renderUpgradeLlm", () => {
+  it("shows upgrade transition", () => {
+    const output = renderUpgradeLlm(createUpgradeData());
+    expect(output).toContain("0.18.0 → 0.19.0");
+  });
+
+  it("shows dry-run info", () => {
+    const output = renderUpgradeLlm(createUpgradeData({ dryRun: true }));
+    expect(output).toContain("Would upgrade");
+    expect(output).toContain("Command:");
+  });
+
+  it("shows already latest", () => {
+    const output = renderUpgradeLlm(createUpgradeData({ alreadyLatest: true }));
+    expect(output).toContain("Already at latest");
+  });
+
+  it("shows offline", () => {
+    const output = renderUpgradeLlm(
+      createUpgradeData({ offline: true, latest: undefined }),
+    );
+    expect(output).toContain("could not reach registry");
+  });
+});
+
+describe("renderUpgradeJson", () => {
+  it("produces valid JSON", () => {
+    const data = createUpgradeData();
+    const parsed = JSON.parse(renderUpgradeJson(data));
+    expect(parsed.pm).toBe("bun");
+    expect(parsed.current).toBe("0.18.0");
+    expect(parsed.latest).toBe("0.19.0");
+  });
+
+  it("includes all fields", () => {
+    const parsed = JSON.parse(renderUpgradeJson(createUpgradeData()));
+    expect(parsed).toHaveProperty("dryRun");
+    expect(parsed).toHaveProperty("alreadyLatest");
+    expect(parsed).toHaveProperty("offline");
+    expect(parsed).toHaveProperty("executed");
+    expect(parsed).toHaveProperty("command");
+  });
+
+  it("handles offline case", () => {
+    const parsed = JSON.parse(
+      renderUpgradeJson(
+        createUpgradeData({ offline: true, latest: undefined }),
+      ),
+    );
+    expect(parsed.offline).toBe(true);
+    expect(parsed.latest).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,68 @@
+import chalk from "chalk";
+import type { UpgradeData } from "../types.js";
+
+/**
+ * Renders `pragma upgrade` output for a plain terminal.
+ *
+ * Shows version comparison, dry-run notice, or completion status with chalk styling.
+ *
+ * @param data - The upgrade outcome data.
+ * @returns A formatted terminal string.
+ */
+function renderUpgradePlain(data: UpgradeData): string {
+  const lines: string[] = [];
+
+  lines.push(`Installed via: ${data.pm} (global)`);
+
+  if (data.offline) {
+    lines.push("Could not reach registry");
+    return lines.join("\n");
+  }
+
+  if (data.alreadyLatest) {
+    lines.push(`Already at latest version (${data.current}).`);
+    return lines.join("\n");
+  }
+
+  lines.push("");
+  lines.push(
+    `@canonical/pragma-cli  ${data.current} → ${chalk.green(data.latest)}`,
+  );
+  lines.push("");
+
+  if (data.dryRun) {
+    lines.push(`Would run: ${chalk.cyan(data.command)}`);
+  } else {
+    lines.push(`Running: ${chalk.cyan(data.command)}`);
+    lines.push("");
+    lines.push(`done. Updated to ${data.latest}.`);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Renders `pragma upgrade` output as condensed Markdown for LLM consumption.
+ *
+ * @param data - The upgrade outcome data.
+ * @returns A single-line Markdown string.
+ */
+function renderUpgradeLlm(data: UpgradeData): string {
+  if (data.offline) return "Upgrade check failed: could not reach registry";
+  if (data.alreadyLatest) return `Already at latest version (${data.current})`;
+  if (data.dryRun)
+    return `Would upgrade: ${data.current} → ${data.latest}\nCommand: ${data.command}`;
+  return `Upgraded: ${data.current} → ${data.latest}`;
+}
+
+/**
+ * Renders `pragma upgrade` output as indented JSON.
+ *
+ * @param data - The upgrade outcome data.
+ * @returns A JSON string.
+ */
+function renderUpgradeJson(data: UpgradeData): string {
+  return JSON.stringify(data, null, 2);
+}
+
+export { renderUpgradeJson, renderUpgradeLlm, renderUpgradePlain };

package/src/domains/info/index.ts

@@ -0,0 +1,7 @@
+/**
+ * @module Info domain barrel.
+ *
+ * Provides the `pragma info` and `pragma upgrade` commands.
+ */
+
+export { infoCommand, upgradeCommand } from "./commands/index.js";

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

@@ -0,0 +1,124 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import checkRegistryVersion from "./checkRegistryVersion.js";
+
+describe("checkRegistryVersion", () => {
+  const originalFetch = globalThis.fetch;
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it("returns latest version for normal channel", async () => {
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () =>
+        Promise.resolve({
+          "dist-tags": { latest: "0.19.0", experimental: "0.20.0-exp.1" },
+        }),
+    });
+
+    const result = await checkRegistryVersion(
+      "@canonical/pragma-cli",
+      "normal",
+    );
+
+    expect(result).toEqual({ latest: "0.19.0", distTag: "latest" });
+    expect(globalThis.fetch).toHaveBeenCalledWith(
+      "https://registry.npmjs.org/%40canonical%2Fpragma-cli",
+      expect.objectContaining({
+        headers: { Accept: "application/json" },
+      }),
+    );
+  });
+
+  it("returns experimental version for experimental channel", async () => {
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () =>
+        Promise.resolve({
+          "dist-tags": { latest: "0.19.0", experimental: "0.20.0-exp.1" },
+        }),
+    });
+
+    const result = await checkRegistryVersion(
+      "@canonical/pragma-cli",
+      "experimental",
+    );
+
+    expect(result).toEqual({
+      latest: "0.20.0-exp.1",
+      distTag: "experimental",
+    });
+  });
+
+  it("returns next version for prerelease channel", async () => {
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () =>
+        Promise.resolve({
+          "dist-tags": { latest: "0.19.0", next: "0.20.0-rc.1" },
+        }),
+    });
+
+    const result = await checkRegistryVersion(
+      "@canonical/pragma-cli",
+      "prerelease",
+    );
+
+    expect(result).toEqual({ latest: "0.20.0-rc.1", distTag: "next" });
+  });
+
+  it("returns undefined when registry responds with non-ok status", async () => {
+    globalThis.fetch = vi.fn().mockResolvedValue({ ok: false, status: 404 });
+
+    const result = await checkRegistryVersion(
+      "@canonical/pragma-cli",
+      "normal",
+    );
+
+    expect(result).toBeUndefined();
+  });
+
+  it("returns undefined when dist-tag is missing", async () => {
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({ "dist-tags": { latest: "0.19.0" } }),
+    });
+
+    const result = await checkRegistryVersion(
+      "@canonical/pragma-cli",
+      "prerelease",
+    );
+
+    expect(result).toBeUndefined();
+  });
+
+  it("returns undefined when fetch throws (offline)", async () => {
+    globalThis.fetch = vi.fn().mockRejectedValue(new Error("network error"));
+
+    const result = await checkRegistryVersion(
+      "@canonical/pragma-cli",
+      "normal",
+    );
+
+    expect(result).toBeUndefined();
+  });
+
+  it("returns undefined when response has no dist-tags", async () => {
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({}),
+    });
+
+    const result = await checkRegistryVersion(
+      "@canonical/pragma-cli",
+      "normal",
+    );
+
+    expect(result).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,45 @@
+import type { Channel } from "#constants";
+import { DIST_TAG_MAP, REGISTRY_TIMEOUT_MS } from "../constants.js";
+import type { RegistryCheckResult } from "../types.js";
+
+/**
+ * Checks the npm registry for the latest published version of a package.
+ *
+ * Returns `undefined` when offline or when the registry does not respond
+ * within the configured timeout ({@link REGISTRY_TIMEOUT_MS}).
+ *
+ * @note Impure
+ *
+ * @param packageName - The npm package name (e.g. `@canonical/pragma-cli`).
+ * @param channel - The release channel determining which dist-tag to check.
+ * @returns A {@link RegistryCheckResult} with the latest version, or `undefined` on failure.
+ */
+async function checkRegistryVersion(
+  packageName: string,
+  channel: Channel,
+): Promise<RegistryCheckResult | undefined> {
+  const distTag = DIST_TAG_MAP[channel];
+  const url = `https://registry.npmjs.org/${encodeURIComponent(packageName)}`;
+
+  try {
+    const response = await fetch(url, {
+      signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS),
+      headers: { Accept: "application/json" },
+    });
+
+    if (!response.ok) return undefined;
+
+    const data = (await response.json()) as {
+      "dist-tags"?: Record<string, string>;
+    };
+
+    const version = data["dist-tags"]?.[distTag];
+    if (!version) return undefined;
+
+    return { latest: version, distTag };
+  } catch {
+    return undefined;
+  }
+}
+
+export default checkRegistryVersion;

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

@@ -0,0 +1,111 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const readConfigMock = vi.fn();
+const detectInstallSourceMock = vi.fn();
+const bootStoreMock = vi.fn();
+const checkRegistryVersionMock = vi.fn();
+const collectStoreSummaryMock = vi.fn();
+
+vi.mock("#config", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("#config")>()),
+  readConfig: readConfigMock,
+}));
+
+vi.mock("#package-manager", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("#package-manager")>();
+  return {
+    ...actual,
+    detectInstallSource: detectInstallSourceMock,
+    PM_COMMANDS: {
+      ...actual.PM_COMMANDS,
+      bun: {
+        ...actual.PM_COMMANDS.bun,
+        update: (pkg: string) => `bun update ${pkg}`,
+      },
+    },
+  };
+});
+
+vi.mock("../../shared/bootStore.js", () => ({
+  bootStore: bootStoreMock,
+}));
+
+vi.mock("./checkRegistryVersion.js", () => ({
+  default: checkRegistryVersionMock,
+}));
+
+vi.mock("./collectStoreSummary.js", () => ({
+  collectStoreSummary: collectStoreSummaryMock,
+}));
+
+describe("collectInfo", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    detectInstallSourceMock.mockReturnValue({
+      packageManager: "bun",
+      scope: "global",
+      label: "bun (global)",
+    });
+    readConfigMock.mockReturnValue({ tier: "apps/lxd", channel: "normal" });
+  });
+
+  it("includes update information and store summary when available", async () => {
+    const dispose = vi.fn();
+    bootStoreMock.mockResolvedValue({ dispose });
+    checkRegistryVersionMock.mockResolvedValue({
+      latest: "9.9.9",
+      distTag: "latest",
+    });
+    collectStoreSummaryMock.mockResolvedValue({
+      tripleCount: 42,
+      graphNames: ["default"],
+    });
+
+    const { default: collectInfo } = await import("./collectInfo.js");
+    const result = await collectInfo("/workspace");
+
+    expect(result.update).toEqual({
+      current: expect.any(String),
+      latest: "9.9.9",
+      command: "bun update @canonical/pragma-cli",
+    });
+    expect(result.installSource).toBe("bun (global)");
+    expect(result.updateSkipped).toBe(false);
+    expect(result.store).toEqual({ tripleCount: 42, graphNames: ["default"] });
+    expect(result.tierChain.length).toBeGreaterThan(0);
+    expect(dispose).toHaveBeenCalledTimes(1);
+  });
+
+  it("marks update as skipped and omits store when registry and store are unavailable", async () => {
+    checkRegistryVersionMock.mockResolvedValue(undefined);
+    bootStoreMock.mockRejectedValue(new Error("store unavailable"));
+
+    const { default: collectInfo } = await import("./collectInfo.js");
+    const result = await collectInfo("/workspace");
+
+    expect(result.update).toBeUndefined();
+    expect(result.updateSkipped).toBe(true);
+    expect(result.store).toBeUndefined();
+  });
+
+  it("omits the update section when already on the latest version", async () => {
+    const { VERSION } = await import("#constants");
+    const dispose = vi.fn();
+    bootStoreMock.mockResolvedValue({ dispose });
+    checkRegistryVersionMock.mockResolvedValue({
+      latest: VERSION,
+      distTag: "latest",
+    });
+    collectStoreSummaryMock.mockResolvedValue({
+      tripleCount: 10,
+      graphNames: ["default"],
+    });
+
+    const { default: collectInfo } = await import("./collectInfo.js");
+    const result = await collectInfo("/workspace");
+
+    expect(result.update).toBeUndefined();
+    expect(result.updateSkipped).toBe(false);
+    expect(result.store?.tripleCount).toBe(10);
+  });
+});

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

@@ -0,0 +1,68 @@
+import { readConfig } from "#config";
+import { VERSION } from "#constants";
+import { detectInstallSource, PM_COMMANDS } from "#package-manager";
+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 checkRegistryVersion from "./checkRegistryVersion.js";
+import { collectStoreSummary } from "./collectStoreSummary.js";
+
+/**
+ * Collects all data for the `pragma info` command.
+ *
+ * Reads local config, detects the package manager, checks the npm registry
+ * for updates, boots a ke store, and gathers store summary statistics.
+ *
+ * @note Impure
+ *
+ * @param cwd - The current working directory used to locate `pragma.config.json`.
+ * @returns A fully populated {@link InfoData} object.
+ */
+export default async function collectInfo(cwd: string): Promise<InfoData> {
+  const install = detectInstallSource();
+  const pm = install.packageManager;
+  const config = readConfig(cwd);
+  const tierChain = resolveTierChain(config.tier);
+  const channelReleases = CHANNEL_RELEASES[config.channel];
+
+  const registryResult = await checkRegistryVersion(
+    "@canonical/pragma-cli",
+    config.channel,
+  );
+
+  let update: InfoData["update"];
+  const updateSkipped = registryResult === undefined;
+  if (registryResult && registryResult.latest !== VERSION) {
+    update = {
+      current: VERSION,
+      latest: registryResult.latest,
+      command: PM_COMMANDS[pm].update("@canonical/pragma-cli"),
+    };
+  }
+
+  let store: InfoData["store"];
+  let keStore: Awaited<ReturnType<typeof bootStore>> | undefined;
+  try {
+    keStore = await bootStore({ cwd });
+    store = await collectStoreSummary(keStore);
+  } catch {
+    // Store unavailable — show info without store section
+  } finally {
+    keStore?.dispose();
+  }
+
+  return {
+    version: VERSION,
+    pm,
+    installSource: install.label,
+    configPath: "pragma.config.json",
+    tier: config.tier,
+    tierChain,
+    channel: config.channel,
+    channelReleases: [...channelReleases],
+    update,
+    updateSkipped,
+    store,
+  };
+}

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

@@ -0,0 +1,61 @@
+import type { Store } from "@canonical/ke";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { createTestStore, DS_ONTOLOGY_TTL, DS_TIERS_TTL } from "#testing";
+import { collectStoreSummary } from "./collectStoreSummary.js";
+
+describe("collectStoreSummary", () => {
+  describe("with default graph only", () => {
+    let store: Store;
+    let cleanup: () => void;
+
+    beforeAll(async () => {
+      const result = await createTestStore({
+        ttl: [DS_ONTOLOGY_TTL, DS_TIERS_TTL].join("\n"),
+      });
+      store = result.store;
+      cleanup = result.cleanup;
+    });
+
+    afterAll(() => {
+      cleanup();
+    });
+
+    it("returns a positive triple count", async () => {
+      const summary = await collectStoreSummary(store);
+      expect(summary.tripleCount).toBeGreaterThan(0);
+    });
+
+    it("returns empty graph names when no named graphs", async () => {
+      const summary = await collectStoreSummary(store);
+      expect(summary.graphNames).toEqual([]);
+    });
+  });
+
+  describe("with named graphs", () => {
+    let store: Store;
+    let cleanup: () => void;
+
+    beforeAll(async () => {
+      const result = await createTestStore({
+        ttl: DS_ONTOLOGY_TTL,
+        graphs: [{ graph: "urn:test:tiers", ttl: DS_TIERS_TTL }],
+      });
+      store = result.store;
+      cleanup = result.cleanup;
+    });
+
+    afterAll(() => {
+      cleanup();
+    });
+
+    it("returns triple count including named graphs", async () => {
+      const summary = await collectStoreSummary(store);
+      expect(summary.tripleCount).toBeGreaterThan(0);
+    });
+
+    it("lists named graph URIs", async () => {
+      const summary = await collectStoreSummary(store);
+      expect(summary.graphNames).toContain("urn:test:tiers");
+    });
+  });
+});

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

@@ -0,0 +1,42 @@
+import type { Store } from "@canonical/ke";
+import { buildQuery } from "../../shared/buildQuery.js";
+import type { StoreSummary } from "../types.js";
+
+/**
+ * Queries the ke store for total triple count and named graph URIs.
+ *
+ * @note Queries ke store
+ *
+ * @param store - The ke store to query.
+ * @returns A {@link StoreSummary} with `tripleCount` and `graphNames`.
+ */
+async function collectStoreSummary(store: Store): Promise<StoreSummary> {
+  const countResult = await store.query(
+    buildQuery("SELECT (COUNT(*) AS ?count) WHERE { ?s ?p ?o }"),
+  );
+
+  let tripleCount = 0;
+  if (countResult.type === "select") {
+    const first = countResult.bindings[0];
+    if (first) {
+      tripleCount = Number.parseInt(first.count ?? "0", 10) || 0;
+    }
+  }
+
+  const graphResult = await store.query(
+    buildQuery(
+      "SELECT DISTINCT ?g WHERE { GRAPH ?g { ?s ?p ?o } } ORDER BY ?g",
+    ),
+  );
+
+  const graphNames: string[] = [];
+  if (graphResult.type === "select") {
+    for (const binding of graphResult.bindings) {
+      if (binding.g) graphNames.push(binding.g);
+    }
+  }
+
+  return { tripleCount, graphNames };
+}
+
+export { collectStoreSummary };

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

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