@canonical/pragma-cli 0.18.0

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

@@ -0,0 +1,183 @@
+import { execSync } from "node:child_process";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const {
+  readConfigMock,
+  detectPackageManagerMock,
+  renderUpgradeJsonMock,
+  renderUpgradeLlmMock,
+  renderUpgradePlainMock,
+  checkRegistryVersionMock,
+} = vi.hoisted(() => ({
+  readConfigMock: vi.fn(),
+  detectPackageManagerMock: vi.fn(),
+  renderUpgradeJsonMock: vi.fn(() => "json"),
+  renderUpgradeLlmMock: vi.fn(() => "llm"),
+  renderUpgradePlainMock: vi.fn(() => "plain"),
+  checkRegistryVersionMock: vi.fn(),
+}));
+
+vi.mock("node:child_process", () => ({
+  execSync: 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,
+    detectPackageManager: detectPackageManagerMock,
+    PM_COMMANDS: {
+      ...actual.PM_COMMANDS,
+      bun: {
+        ...actual.PM_COMMANDS.bun,
+        update: (pkg: string) => `bun update ${pkg}`,
+      },
+    },
+  };
+});
+
+vi.mock("../formatters/index.js", () => ({
+  renderUpgradeJson: renderUpgradeJsonMock,
+  renderUpgradeLlm: renderUpgradeLlmMock,
+  renderUpgradePlain: renderUpgradePlainMock,
+}));
+
+vi.mock("../operations/checkRegistryVersion.js", () => ({
+  default: checkRegistryVersionMock,
+}));
+
+import upgradeCommand from "./upgrade.js";
+
+describe("upgradeCommand", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    detectPackageManagerMock.mockReturnValue("bun");
+    readConfigMock.mockReturnValue({ tier: undefined, channel: "normal" });
+  });
+
+  it("has path ['upgrade']", () => {
+    expect(upgradeCommand.path).toEqual(["upgrade"]);
+  });
+
+  it("has a description", () => {
+    expect(upgradeCommand.description).toBeTruthy();
+  });
+
+  it("has dryRun parameter", () => {
+    expect(upgradeCommand.parameters).toHaveLength(1);
+    expect(upgradeCommand.parameters[0].name).toBe("dryRun");
+    expect(upgradeCommand.parameters[0].type).toBe("boolean");
+    expect(upgradeCommand.parameters[0].default).toBe(false);
+  });
+
+  it("has an execute function", () => {
+    expect(typeof upgradeCommand.execute).toBe("function");
+  });
+
+  it("returns offline upgrade information when registry lookup fails", async () => {
+    checkRegistryVersionMock.mockResolvedValue(undefined);
+
+    const result = await upgradeCommand.execute(
+      {},
+      { cwd: "/workspace", globalFlags: { llm: false, format: "text" } },
+    );
+
+    expect(result.tag).toBe("output");
+    if (result.tag === "output") {
+      expect(result.render.plain(result.value)).toBe("plain");
+      expect(renderUpgradePlainMock).toHaveBeenCalledWith(
+        expect.objectContaining({ offline: true, executed: false }),
+      );
+    }
+  });
+
+  it("returns already-latest information when versions match", async () => {
+    const { VERSION } = await import("#constants");
+    checkRegistryVersionMock.mockResolvedValue({
+      latest: VERSION,
+      distTag: "latest",
+    });
+
+    const result = await upgradeCommand.execute(
+      {},
+      { cwd: "/workspace", globalFlags: { llm: true, format: "text" } },
+    );
+
+    expect(result.tag).toBe("output");
+    if (result.tag === "output") {
+      expect(result.render.plain(result.value)).toBe("llm");
+      expect(renderUpgradeLlmMock).toHaveBeenCalledWith(
+        expect.objectContaining({ alreadyLatest: true, offline: false }),
+      );
+    }
+  });
+
+  it("does not execute the upgrade command during dry runs", async () => {
+    checkRegistryVersionMock.mockResolvedValue({
+      latest: "9.9.9",
+      distTag: "latest",
+    });
+
+    const result = await upgradeCommand.execute(
+      { dryRun: true },
+      { cwd: "/workspace", globalFlags: { llm: true, format: "json" } },
+    );
+
+    expect(execSync).not.toHaveBeenCalled();
+    expect(result.tag).toBe("output");
+    if (result.tag === "output") {
+      expect(result.render.plain(result.value)).toBe("json");
+      expect(renderUpgradeJsonMock).toHaveBeenCalledWith(
+        expect.objectContaining({ dryRun: true, executed: false }),
+      );
+    }
+  });
+
+  it("executes the upgrade command when needed", async () => {
+    checkRegistryVersionMock.mockResolvedValue({
+      latest: "9.9.9",
+      distTag: "latest",
+    });
+
+    const result = await upgradeCommand.execute(
+      {},
+      { cwd: "/workspace", globalFlags: { llm: false, format: "text" } },
+    );
+
+    expect(execSync).toHaveBeenCalledWith("bun update @canonical/pragma-cli", {
+      stdio: "inherit",
+    });
+    expect(result.tag).toBe("output");
+    if (result.tag === "output") {
+      expect(result.render.plain(result.value)).toBe("plain");
+      expect(renderUpgradePlainMock).toHaveBeenCalledWith(
+        expect.objectContaining({ executed: true, offline: false }),
+      );
+    }
+  });
+
+  it("throws a pragma error when the upgrade command fails", async () => {
+    checkRegistryVersionMock.mockResolvedValue({
+      latest: "9.9.9",
+      distTag: "latest",
+    });
+    const execSyncMock = execSync as unknown as {
+      mockImplementation: (fn: () => never) => unknown;
+    };
+    execSyncMock.mockImplementation(() => {
+      throw new Error("permission denied");
+    });
+
+    await expect(
+      upgradeCommand.execute(
+        {},
+        { cwd: "/workspace", globalFlags: { llm: false, format: "text" } },
+      ),
+    ).rejects.toThrow("Upgrade command failed: permission denied");
+  });
+});

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

@@ -0,0 +1,150 @@
+import { execSync } from "node:child_process";
+import type { CommandDefinition, CommandResult } from "@canonical/cli-core";
+import { readConfig } from "#config";
+import { VERSION } from "#constants";
+import { PragmaError } from "#error";
+import { detectPackageManager, PM_COMMANDS } from "#package-manager";
+import {
+  renderUpgradeJson,
+  renderUpgradeLlm,
+  renderUpgradePlain,
+} from "../formatters/index.js";
+import checkRegistryVersion from "../operations/checkRegistryVersion.js";
+import type { UpgradeData } from "../types.js";
+
+/**
+ * Selects the appropriate upgrade renderer based on global CLI flags.
+ *
+ * @param flags - Global flags indicating output format.
+ * @returns A render function mapping {@link UpgradeData} to a string.
+ */
+function selectUpgradeRenderer(flags: {
+  llm: boolean;
+  format: "text" | "json";
+}): (data: UpgradeData) => string {
+  if (flags.format === "json") return renderUpgradeJson;
+  if (flags.llm) return renderUpgradeLlm;
+  return renderUpgradePlain;
+}
+
+/**
+ * Wraps upgrade data in a command result with the selected renderer.
+ *
+ * @param data - The upgrade outcome data.
+ * @param flags - Global flags indicating output format.
+ * @returns A command result ready for display.
+ */
+function buildUpgradeResult(
+  data: UpgradeData,
+  flags: { llm: boolean; format: "text" | "json" },
+): CommandResult {
+  const render = selectUpgradeRenderer(flags);
+  return { tag: "output", value: data, render: { plain: render } };
+}
+
+/**
+ * Executes the upgrade workflow: checks the registry, optionally runs the
+ * package-manager update command, and returns the result.
+ *
+ * @note Impure
+ *
+ * @param params - Command parameters (`dryRun` boolean).
+ * @param ctx - Execution context with `cwd` and `globalFlags`.
+ * @returns A command result describing the upgrade outcome.
+ * @throws PragmaError if the upgrade shell command fails.
+ */
+async function executeUpgrade(
+  params: Record<string, unknown>,
+  ctx: { cwd: string; globalFlags: { llm: boolean; format: "text" | "json" } },
+): Promise<CommandResult> {
+  const dryRun = params.dryRun === true;
+  const pm = detectPackageManager();
+  const config = readConfig(ctx.cwd);
+  const command = PM_COMMANDS[pm].update("@canonical/pragma-cli");
+
+  const registryResult = await checkRegistryVersion(
+    "@canonical/pragma-cli",
+    config.channel,
+  );
+
+  if (!registryResult) {
+    return buildUpgradeResult(
+      {
+        pm,
+        current: VERSION,
+        latest: undefined,
+        command,
+        dryRun,
+        alreadyLatest: false,
+        offline: true,
+        executed: false,
+      },
+      ctx.globalFlags,
+    );
+  }
+
+  if (registryResult.latest === VERSION) {
+    return buildUpgradeResult(
+      {
+        pm,
+        current: VERSION,
+        latest: registryResult.latest,
+        command,
+        dryRun,
+        alreadyLatest: true,
+        offline: false,
+        executed: false,
+      },
+      ctx.globalFlags,
+    );
+  }
+
+  let executed = false;
+  if (!dryRun) {
+    try {
+      execSync(command, { stdio: "inherit" });
+      executed = true;
+    } catch (error) {
+      throw PragmaError.internalError(
+        `Upgrade command failed: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+
+  return buildUpgradeResult(
+    {
+      pm,
+      current: VERSION,
+      latest: registryResult.latest,
+      command,
+      dryRun,
+      alreadyLatest: false,
+      offline: false,
+      executed,
+    },
+    ctx.globalFlags,
+  );
+}
+
+/**
+ * The `pragma upgrade` command definition.
+ *
+ * Upgrades the pragma CLI to the latest version via the detected package manager.
+ *
+ * @note Impure
+ */
+const upgradeCommand: CommandDefinition = {
+  path: ["upgrade"],
+  description: "Upgrade the pragma CLI to the latest version",
+  parameters: [
+    {
+      name: "dryRun",
+      description: "Show what would happen without running the upgrade",
+      type: "boolean",
+      default: false,
+    },
+  ],
+  execute: executeUpgrade,
+};
+
+export default upgradeCommand;

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

@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest";
+import { DIST_TAG_MAP, REGISTRY_TIMEOUT_MS } from "./constants.js";
+
+describe("DIST_TAG_MAP", () => {
+  it("maps normal to latest", () => {
+    expect(DIST_TAG_MAP.normal).toBe("latest");
+  });
+
+  it("maps experimental to experimental", () => {
+    expect(DIST_TAG_MAP.experimental).toBe("experimental");
+  });
+
+  it("maps prerelease to next", () => {
+    expect(DIST_TAG_MAP.prerelease).toBe("next");
+  });
+});
+
+describe("REGISTRY_TIMEOUT_MS", () => {
+  it("is 3 seconds", () => {
+    expect(REGISTRY_TIMEOUT_MS).toBe(3_000);
+  });
+});

package/src/domains/info/constants.ts

@@ -0,0 +1,15 @@
+import type { Channel } from "../../constants.js";
+
+/**
+ * Maps each release {@link Channel} to its corresponding npm dist-tag.
+ */
+const DIST_TAG_MAP: Record<Channel, string> = {
+  normal: "latest",
+  experimental: "experimental",
+  prerelease: "next",
+};
+
+/** Timeout in milliseconds for npm registry HTTP requests. */
+const REGISTRY_TIMEOUT_MS = 3_000;
+
+export { DIST_TAG_MAP, REGISTRY_TIMEOUT_MS };

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

@@ -0,0 +1,8 @@
+/** @module Barrel for info/upgrade formatters. */
+
+export { renderInfoJson, renderInfoLlm, renderInfoPlain } from "./info.js";
+export {
+  renderUpgradeJson,
+  renderUpgradeLlm,
+  renderUpgradePlain,
+} from "./upgrade.js";

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

@@ -0,0 +1,173 @@
+import { describe, expect, it } from "vitest";
+import type { InfoData } from "../types.js";
+import { renderInfoJson, renderInfoLlm, renderInfoPlain } from "./info.js";
+
+function createInfoData(overrides: Partial<InfoData> = {}): InfoData {
+  return {
+    version: "0.18.0",
+    pm: "bun",
+    installSource: "bun (global)",
+    configPath: "pragma.config.json",
+    tier: "apps/lxd",
+    tierChain: ["global", "apps", "apps/lxd"],
+    channel: "normal",
+    channelReleases: ["stable"],
+    update: undefined,
+    updateSkipped: false,
+    store: { tripleCount: 12847, graphNames: ["urn:pragma:standards"] },
+    ...overrides,
+  };
+}
+
+describe("renderInfoPlain", () => {
+  it("includes version", () => {
+    const output = renderInfoPlain(createInfoData());
+    expect(output).toContain("pragma v0.18.0");
+  });
+
+  it("includes install method", () => {
+    const output = renderInfoPlain(createInfoData());
+    expect(output).toContain("bun (global)");
+  });
+
+  it("supports local install output", () => {
+    const output = renderInfoPlain(
+      createInfoData({ installSource: "bun (local)" }),
+    );
+    expect(output).toContain("bun (local)");
+  });
+
+  it("includes tier chain", () => {
+    const output = renderInfoPlain(createInfoData());
+    expect(output).toContain("global → apps → apps/lxd");
+  });
+
+  it("shows (none) when tier is undefined", () => {
+    const output = renderInfoPlain(
+      createInfoData({ tier: undefined, tierChain: [] }),
+    );
+    expect(output).toContain("(none)");
+  });
+
+  it("includes channel with releases", () => {
+    const output = renderInfoPlain(createInfoData());
+    expect(output).toContain("normal");
+    expect(output).toContain("stable");
+  });
+
+  it("shows update available", () => {
+    const output = renderInfoPlain(
+      createInfoData({
+        update: {
+          current: "0.18.0",
+          latest: "0.19.0",
+          command: "bun update -g @canonical/pragma-cli",
+        },
+      }),
+    );
+    expect(output).toContain("0.19.0");
+    expect(output).toContain("pragma upgrade");
+  });
+
+  it("shows up to date when no update", () => {
+    const output = renderInfoPlain(createInfoData());
+    expect(output).toContain("Up to date");
+  });
+
+  it("shows offline fallback", () => {
+    const output = renderInfoPlain(createInfoData({ updateSkipped: true }));
+    expect(output).toContain("offline");
+  });
+
+  it("includes store summary", () => {
+    const output = renderInfoPlain(createInfoData());
+    expect(output).toContain("12,847");
+    expect(output).toContain("urn:pragma:standards");
+  });
+
+  it("shows default only when no named graphs", () => {
+    const output = renderInfoPlain(
+      createInfoData({ store: { tripleCount: 100, graphNames: [] } }),
+    );
+    expect(output).toContain("default");
+    expect(output).not.toContain("urn:");
+  });
+
+  it("omits store section when store is undefined", () => {
+    const output = renderInfoPlain(createInfoData({ store: undefined }));
+    expect(output).not.toContain("Triples");
+    expect(output).not.toContain("Graphs");
+  });
+});
+
+describe("renderInfoLlm", () => {
+  it("starts with markdown heading", () => {
+    const output = renderInfoLlm(createInfoData());
+    expect(output).toMatch(/^# pragma v0\.18\.0/);
+  });
+
+  it("includes tier chain", () => {
+    const output = renderInfoLlm(createInfoData());
+    expect(output).toContain("global → apps → apps/lxd");
+  });
+
+  it("includes update info", () => {
+    const output = renderInfoLlm(
+      createInfoData({
+        update: {
+          current: "0.18.0",
+          latest: "0.19.0",
+          command: "bun update -g @canonical/pragma-cli",
+        },
+      }),
+    );
+    expect(output).toContain("0.18.0 → 0.19.0");
+  });
+
+  it("shows up to date", () => {
+    const output = renderInfoLlm(createInfoData());
+    expect(output).toContain("up to date");
+  });
+
+  it("shows offline", () => {
+    const output = renderInfoLlm(createInfoData({ updateSkipped: true }));
+    expect(output).toContain("offline");
+  });
+
+  it("includes store triple count", () => {
+    const output = renderInfoLlm(createInfoData());
+    expect(output).toContain("12,847 triples");
+  });
+});
+
+describe("renderInfoJson", () => {
+  it("produces valid JSON", () => {
+    const data = createInfoData();
+    const output = renderInfoJson(data);
+    const parsed = JSON.parse(output);
+    expect(parsed.version).toBe("0.18.0");
+    expect(parsed.pm).toBe("bun");
+  });
+
+  it("includes all fields", () => {
+    const data = createInfoData();
+    const parsed = JSON.parse(renderInfoJson(data));
+    expect(parsed).toHaveProperty("tier");
+    expect(parsed).toHaveProperty("tierChain");
+    expect(parsed).toHaveProperty("channel");
+    expect(parsed).toHaveProperty("channelReleases");
+    expect(parsed).toHaveProperty("store");
+  });
+
+  it("includes update when available", () => {
+    const data = createInfoData({
+      update: {
+        current: "0.18.0",
+        latest: "0.19.0",
+        command: "bun update -g @canonical/pragma-cli",
+      },
+    });
+    const parsed = JSON.parse(renderInfoJson(data));
+    expect(parsed.update.latest).toBe("0.19.0");
+  });
+});

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

@@ -0,0 +1,116 @@
+import chalk from "chalk";
+import { formatField, formatHeading } from "#pipeline";
+import type { InfoData } from "../types.js";
+
+/**
+ * Renders `pragma info` output for a plain terminal.
+ *
+ * Includes chalk-styled version, config, update status, and store summary.
+ *
+ * @param data - The collected info data.
+ * @returns A formatted terminal string.
+ */
+function renderInfoPlain(data: InfoData): string {
+  const lines: string[] = [];
+
+  lines.push(`pragma v${data.version}`);
+
+  lines.push(formatField("  Installed via:", data.installSource));
+
+  lines.push(formatField("  Config:", data.configPath));
+
+  if (data.tier) {
+    const chain = data.tierChain.join(" → ");
+    lines.push(formatField("    tier:", `${data.tier} (${chain})`));
+  } else {
+    lines.push(formatField("    tier:", "(none)"));
+  }
+
+  const releases = data.channelReleases.join(", ");
+  lines.push(formatField("    channel:", `${data.channel} (${releases})`));
+
+  lines.push("");
+  lines.push(formatHeading("Update"));
+  if (data.update) {
+    lines.push(
+      `  ${data.update.current} → ${chalk.green(data.update.latest)} available`,
+    );
+    lines.push(`  Run ${chalk.cyan(`\`${data.update.command}\``)} to upgrade.`);
+    lines.push(`  Or run ${chalk.cyan("`pragma upgrade`")}.`);
+  } else if (data.updateSkipped) {
+    lines.push("  Upgrade check skipped (offline)");
+  } else {
+    lines.push("  Up to date.");
+  }
+
+  if (data.store) {
+    lines.push("");
+    lines.push(formatHeading("Store"));
+    lines.push(
+      formatField("  Triples:", data.store.tripleCount.toLocaleString()),
+    );
+    if (data.store.graphNames.length > 0) {
+      lines.push(
+        formatField(
+          "  Graphs:",
+          `default, ${data.store.graphNames.join(", ")}`,
+        ),
+      );
+    } else {
+      lines.push(formatField("  Graphs:", "default"));
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Renders `pragma info` output as condensed Markdown for LLM consumption.
+ *
+ * @param data - The collected info data.
+ * @returns A Markdown string.
+ */
+function renderInfoLlm(data: InfoData): string {
+  const lines: string[] = [];
+
+  lines.push(`# pragma v${data.version}`);
+  lines.push(`- Installed via: ${data.installSource}`);
+
+  if (data.tier) {
+    lines.push(`- Tier: ${data.tier} (${data.tierChain.join(" → ")})`);
+  } else {
+    lines.push("- Tier: (none)");
+  }
+  lines.push(`- Channel: ${data.channel} (${data.channelReleases.join(", ")})`);
+
+  if (data.update) {
+    lines.push(
+      `- Update: ${data.update.current} → ${data.update.latest} available`,
+    );
+  } else if (data.updateSkipped) {
+    lines.push("- Update: check skipped (offline)");
+  } else {
+    lines.push("- Update: up to date");
+  }
+
+  if (data.store) {
+    lines.push(`- Store: ${data.store.tripleCount.toLocaleString()} triples`);
+    if (data.store.graphNames.length > 0) {
+      lines.push(`- Graphs: default, ${data.store.graphNames.join(", ")}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Renders `pragma info` output as indented JSON.
+ *
+ * @param data - The collected info data.
+ * @returns A JSON string.
+ */
+function renderInfoJson(data: InfoData): string {
+  return JSON.stringify(data, null, 2);
+}
+
+export { renderInfoJson, renderInfoLlm, renderInfoPlain };