@canonical/pragma-cli 0.25.0 → 0.26.0

package/src/domains/refs/commands/updateRefs.ts

@@ -0,0 +1,52 @@
+/**
+ * CLI command: pragma update-refs
+ *
+ * Fetches/clones git-referenced semantic packages into the local cache.
+ * Store-skip command — does not boot the ke store.
+ */
+
+import type { CommandDefinition } from "@canonical/cli-core";
+import formatUpdateResults from "../formatters/updateRefs.js";
+import updateRefs from "../operations/updateRefs.js";
+
+const updateRefsCommand: CommandDefinition = {
+  path: ["update-refs"],
+  description:
+    "Fetch or clone git-referenced semantic packages into the local cache",
+  parameters: [
+    {
+      name: "package",
+      description: "Update only this package (by name)",
+      type: "string",
+    },
+    {
+      name: "prune",
+      description:
+        "Remove orphaned cache entries that no longer match any configured ref",
+      type: "boolean",
+      default: false,
+    },
+  ],
+  meta: {
+    examples: [
+      "pragma update-refs",
+      "pragma update-refs --package @canonical/design-system",
+      "pragma update-refs --prune",
+    ],
+  },
+  execute: async (params, ctx) => {
+    const results = await updateRefs({
+      cwd: ctx.cwd,
+      package: params.package as string | undefined,
+      prune: params.prune === true,
+    });
+
+    const text = formatUpdateResults(results);
+    process.stdout.write(`${text}\n`);
+
+    const hasErrors = results.some((r) => r.kind === "error");
+    return { tag: "exit" as const, code: hasErrors ? 1 : 0 };
+  },
+};
+
+export default updateRefsCommand;

package/src/domains/refs/formatters/updateRefs.ts

@@ -0,0 +1,27 @@
+/**
+ * Plain-text formatter for update-refs results.
+ */
+
+import type { UpdateResult } from "../operations/updateRefs.js";
+
+const KIND_LABELS: Record<UpdateResult["kind"], string> = {
+  cloned: "cloned",
+  updated: "updated",
+  "up-to-date": "up to date",
+  ok: "ok",
+  skipped: "skipped",
+  error: "ERROR",
+};
+
+export default function formatUpdateResults(
+  results: ReadonlyArray<UpdateResult>,
+): string {
+  if (results.length === 0) return "No packages configured.";
+
+  const lines: string[] = [];
+  for (const r of results) {
+    const label = KIND_LABELS[r.kind] ?? r.kind;
+    lines.push(`${r.pkg}: ${label} — ${r.detail}`);
+  }
+  return lines.join("\n");
+}

package/src/domains/refs/index.ts

@@ -0,0 +1,27 @@
+/** @module Refs domain — package reference resolution and update-refs command. */
+
+import type { CommandDefinition } from "@canonical/cli-core";
+import updateRefsCommand from "./commands/updateRefs.js";
+
+/**
+ * Return all refs command definitions.
+ * Store-skip domain — does not require a booted ke store.
+ */
+export function commands(): CommandDefinition[] {
+  return [updateRefsCommand];
+}
+
+export type {
+  PackageRef,
+  RawPackageEntry,
+  UpdateRefsOptions,
+  UpdateResult,
+} from "./operations/index.js";
+export {
+  cacheRoot,
+  gitCacheDir,
+  globalConfigDir,
+  parsePackageEntry,
+  readGlobalRefs,
+  updateRefs,
+} from "./operations/index.js";

package/src/domains/refs/operations/gitOps.test.ts

@@ -0,0 +1,155 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { cloneRef, fetchRef, isSha, pruneCache } from "./gitOps.js";
+
+describe("isSha", () => {
+  it("recognizes a 7-char hex string", () => {
+    expect(isSha("abc1234")).toBe(true);
+  });
+
+  it("recognizes a 40-char hex string", () => {
+    expect(isSha("abc1234def5678901234567890abcdef12345678")).toBe(true);
+  });
+
+  it("rejects non-hex characters", () => {
+    expect(isSha("main")).toBe(false);
+    expect(isSha("v1.0.0")).toBe(false);
+    expect(isSha("feature/branch")).toBe(false);
+  });
+
+  it("rejects too-short strings", () => {
+    expect(isSha("abc12")).toBe(false);
+  });
+
+  it("rejects uppercase hex", () => {
+    expect(isSha("ABC1234")).toBe(false);
+  });
+});
+
+describe("cloneRef + fetchRef (integration, requires git)", () => {
+  let tmpDir: string;
+  let bareRepo: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "pragma-gitops-"));
+
+    // Create a bare repo to clone from (avoids network)
+    bareRepo = join(tmpDir, "origin.git");
+    execFileSync("git", ["init", "--bare", "-b", "main", bareRepo], {
+      stdio: "pipe",
+    });
+
+    // Push an initial commit to the bare repo via a temp working copy
+    const workDir = join(tmpDir, "work");
+    execFileSync("git", ["clone", bareRepo, workDir], { stdio: "pipe" });
+    execFileSync(
+      "git",
+      ["-C", workDir, "config", "user.email", "test@test.com"],
+      { stdio: "pipe" },
+    );
+    execFileSync("git", ["-C", workDir, "config", "user.name", "Test"], {
+      stdio: "pipe",
+    });
+    execFileSync(
+      "git",
+      ["-C", workDir, "commit", "--allow-empty", "-m", "initial"],
+      { stdio: "pipe" },
+    );
+    execFileSync("git", ["-C", workDir, "push", "origin", "main"], {
+      stdio: "pipe",
+    });
+    // Tag it
+    execFileSync("git", ["-C", workDir, "tag", "v0.1.0"], { stdio: "pipe" });
+    execFileSync("git", ["-C", workDir, "push", "origin", "v0.1.0"], {
+      stdio: "pipe",
+    });
+    // Add another commit for update testing
+    execFileSync(
+      "git",
+      ["-C", workDir, "commit", "--allow-empty", "-m", "second"],
+      { stdio: "pipe" },
+    );
+    execFileSync("git", ["-C", workDir, "push", "origin", "main"], {
+      stdio: "pipe",
+    });
+
+    rmSync(workDir, { recursive: true, force: true });
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("clones a branch ref", () => {
+    const dest = join(tmpDir, "clone-branch");
+    cloneRef(bareRepo, "main", dest);
+    expect(existsSync(join(dest, ".git"))).toBe(true);
+  });
+
+  it("clones a tag ref", () => {
+    const dest = join(tmpDir, "clone-tag");
+    cloneRef(bareRepo, "v0.1.0", dest);
+    expect(existsSync(join(dest, ".git"))).toBe(true);
+  });
+
+  it("clones a SHA ref", () => {
+    // Get the SHA of the initial commit
+    const sha = execFileSync("git", ["-C", bareRepo, "rev-parse", "v0.1.0"], {
+      stdio: "pipe",
+    })
+      .toString()
+      .trim();
+
+    const dest = join(tmpDir, "clone-sha");
+    cloneRef(bareRepo, sha, dest);
+    expect(existsSync(join(dest, ".git"))).toBe(true);
+  });
+
+  it("fetches updates on an existing clone", () => {
+    // Clone at tag (first commit)
+    const dest = join(tmpDir, "clone-fetch");
+    cloneRef(bareRepo, "v0.1.0", dest);
+
+    // Fetch main (which has a second commit)
+    const result = fetchRef(bareRepo, "main", dest);
+    expect(result.updated).toBe(true);
+    expect(result.oldHead).not.toBe(result.newHead);
+  });
+
+  it("reports up-to-date when no changes", () => {
+    const dest = join(tmpDir, "clone-noop");
+    cloneRef(bareRepo, "main", dest);
+
+    const result = fetchRef(bareRepo, "main", dest);
+    expect(result.updated).toBe(false);
+    expect(result.oldHead).toBe(result.newHead);
+  });
+});
+
+describe("pruneCache", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "pragma-prune-"));
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("removes an existing directory", () => {
+    const dir = join(tmpDir, "to-remove");
+    execFileSync("mkdir", ["-p", dir]);
+    expect(existsSync(dir)).toBe(true);
+    pruneCache(dir);
+    expect(existsSync(dir)).toBe(false);
+  });
+
+  it("does nothing for a non-existent directory", () => {
+    pruneCache(join(tmpDir, "does-not-exist"));
+    // no throw
+  });
+});

package/src/domains/refs/operations/gitOps.ts

@@ -0,0 +1,92 @@
+/**
+ * Git operations for managing cached package clones.
+ *
+ * All operations use execFileSync with shell: false for security.
+ * Relies entirely on the user's git client for authentication
+ * (SSH keys, credential helpers). Zero custom auth logic.
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { dirname } from "node:path";
+
+/** Check whether a ref looks like a commit SHA (7-40 hex chars). */
+export function isSha(ref: string): boolean {
+  return /^[0-9a-f]{7,40}$/.test(ref);
+}
+
+/**
+ * Clone a repository at a specific ref into a destination directory.
+ * Uses shallow clone (--depth 1) for speed.
+ *
+ * @param url - Git remote URL (https:// or ssh://).
+ * @param ref - Branch, tag, or commit SHA.
+ * @param dest - Target directory (must not exist).
+ */
+export function cloneRef(url: string, ref: string, dest: string): void {
+  mkdirSync(dirname(dest), { recursive: true });
+
+  if (isSha(ref)) {
+    // Git doesn't support shallow clone by SHA directly.
+    // Init, fetch the specific commit, checkout.
+    mkdirSync(dest, { recursive: true });
+    git(dest, ["init"]);
+    git(dest, ["fetch", "--depth", "1", url, ref]);
+    git(dest, ["checkout", "FETCH_HEAD"]);
+  } else {
+    // Branches and tags: --branch works with --depth 1
+    execFileSync("git", ["clone", "--depth", "1", "--branch", ref, url, dest], {
+      stdio: "pipe",
+    });
+  }
+}
+
+/**
+ * Update an existing cached clone by fetching the latest for its ref.
+ *
+ * @param url - Git remote URL.
+ * @param ref - Branch, tag, or commit SHA.
+ * @param dest - Existing cache directory.
+ * @returns Whether the HEAD changed after fetch.
+ */
+export function fetchRef(
+  url: string,
+  ref: string,
+  dest: string,
+): { updated: boolean; oldHead: string; newHead: string } {
+  const oldHead = gitOutput(dest, ["rev-parse", "HEAD"]);
+
+  if (isSha(ref)) {
+    git(dest, ["fetch", "--depth", "1", url, ref]);
+    git(dest, ["checkout", "FETCH_HEAD"]);
+  } else {
+    git(dest, ["fetch", "--depth", "1", url, ref]);
+    git(dest, ["checkout", "FETCH_HEAD"]);
+  }
+
+  const newHead = gitOutput(dest, ["rev-parse", "HEAD"]);
+  return { updated: oldHead !== newHead, oldHead, newHead };
+}
+
+/**
+ * Remove a cached directory.
+ */
+export function pruneCache(dir: string): void {
+  if (existsSync(dir)) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Run a git command in a directory. Throws on non-zero exit. */
+function git(cwd: string, args: string[]): void {
+  execFileSync("git", args, { cwd, stdio: "pipe" });
+}
+
+/** Run a git command and return trimmed stdout. */
+function gitOutput(cwd: string, args: string[]): string {
+  return execFileSync("git", args, { cwd, stdio: "pipe" }).toString().trim();
+}

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

@@ -0,0 +1,10 @@
+/** @module Refs operations — parsing, resolution, caching, and update logic. */
+
+export { cloneRef, fetchRef, isSha, pruneCache } from "./gitOps.js";
+export type { PackageRef, RawPackageEntry } from "./parseRef.js";
+export { parsePackageEntry } from "./parseRef.js";
+export { cacheRoot, gitCacheDir, globalConfigDir } from "./paths.js";
+export { default as readGlobalRefs } from "./readGlobalRefs.js";
+
+export type { UpdateRefsOptions, UpdateResult } from "./updateRefs.js";
+export { default as updateRefs } from "./updateRefs.js";

package/src/domains/refs/operations/parseRef.test.ts

@@ -0,0 +1,157 @@
+import { describe, expect, it } from "vitest";
+import { PragmaError } from "../../../error/index.js";
+import { parsePackageEntry } from "./parseRef.js";
+
+describe("parsePackageEntry", () => {
+  describe("npm references", () => {
+    it("parses a bare string as npm", () => {
+      const ref = parsePackageEntry("@canonical/design-system");
+      expect(ref).toEqual({ kind: "npm", pkg: "@canonical/design-system" });
+    });
+
+    it("parses an object without source as npm", () => {
+      const ref = parsePackageEntry({ name: "@canonical/design-system" });
+      expect(ref).toEqual({ kind: "npm", pkg: "@canonical/design-system" });
+    });
+
+    it("parses an object with undefined source as npm", () => {
+      const ref = parsePackageEntry({
+        name: "@canonical/design-system",
+        source: undefined,
+      });
+      expect(ref).toEqual({ kind: "npm", pkg: "@canonical/design-system" });
+    });
+  });
+
+  describe("file references", () => {
+    it("parses file:// source with absolute path", () => {
+      const ref = parsePackageEntry({
+        name: "@canonical/design-system",
+        source: "file:///home/user/code/design-system",
+      });
+      expect(ref).toEqual({
+        kind: "file",
+        pkg: "@canonical/design-system",
+        path: "/home/user/code/design-system",
+      });
+    });
+
+    it("parses file:// source with relative path", () => {
+      const ref = parsePackageEntry({
+        name: "@canonical/design-system",
+        source: "file://./local-packages/design-system",
+      });
+      expect(ref).toEqual({
+        kind: "file",
+        pkg: "@canonical/design-system",
+        path: "./local-packages/design-system",
+      });
+    });
+
+    it("throws on empty file:// path", () => {
+      expect(() =>
+        parsePackageEntry({
+          name: "@canonical/design-system",
+          source: "file://",
+        }),
+      ).toThrow(PragmaError);
+    });
+  });
+
+  describe("git references", () => {
+    it("parses git+https:// source with branch ref", () => {
+      const ref = parsePackageEntry({
+        name: "@canonical/design-system",
+        source: "git+https://github.com/canonical/design-system.git#main",
+      });
+      expect(ref).toEqual({
+        kind: "git",
+        pkg: "@canonical/design-system",
+        url: "https://github.com/canonical/design-system.git",
+        ref: "main",
+      });
+    });
+
+    it("parses git+https:// source with tag ref", () => {
+      const ref = parsePackageEntry({
+        name: "@canonical/design-system",
+        source: "git+https://github.com/canonical/design-system.git#v0.3.0",
+      });
+      expect(ref).toEqual({
+        kind: "git",
+        pkg: "@canonical/design-system",
+        url: "https://github.com/canonical/design-system.git",
+        ref: "v0.3.0",
+      });
+    });
+
+    it("parses git+https:// source with SHA ref", () => {
+      const ref = parsePackageEntry({
+        name: "@canonical/design-system",
+        source:
+          "git+https://github.com/canonical/design-system.git#abc1234def5678",
+      });
+      expect(ref).toEqual({
+        kind: "git",
+        pkg: "@canonical/design-system",
+        url: "https://github.com/canonical/design-system.git",
+        ref: "abc1234def5678",
+      });
+    });
+
+    it("parses git+ssh:// source", () => {
+      const ref = parsePackageEntry({
+        name: "@canonical/design-system",
+        source: "git+ssh://git@github.com/canonical/design-system.git#main",
+      });
+      expect(ref).toEqual({
+        kind: "git",
+        pkg: "@canonical/design-system",
+        url: "ssh://git@github.com/canonical/design-system.git",
+        ref: "main",
+      });
+    });
+
+    it("throws on git URL without #ref", () => {
+      expect(() =>
+        parsePackageEntry({
+          name: "@canonical/design-system",
+          source: "git+https://github.com/canonical/design-system.git",
+        }),
+      ).toThrow(PragmaError);
+    });
+
+    it("throws on git URL with empty ref after #", () => {
+      expect(() =>
+        parsePackageEntry({
+          name: "@canonical/design-system",
+          source: "git+https://github.com/canonical/design-system.git#",
+        }),
+      ).toThrow(PragmaError);
+    });
+  });
+
+  describe("invalid entries", () => {
+    it("throws on unknown source scheme", () => {
+      expect(() =>
+        parsePackageEntry({
+          name: "@canonical/design-system",
+          source: "https://example.com/package.tar.gz",
+        }),
+      ).toThrow(PragmaError);
+    });
+
+    it("throws on empty name", () => {
+      expect(() => parsePackageEntry({ name: "" })).toThrow(PragmaError);
+    });
+
+    it("throws on non-string source", () => {
+      expect(() =>
+        parsePackageEntry({
+          name: "@canonical/design-system",
+          source: 42 as unknown as string,
+        }),
+      ).toThrow(PragmaError);
+    });
+  });
+});

package/src/domains/refs/operations/parseRef.ts

@@ -0,0 +1,114 @@
+/**
+ * Package reference parser.
+ *
+ * Parses pragma.config.json `packages` entries into a discriminated union
+ * of resolution strategies: npm (require.resolve), file (local path), or
+ * git (cached shallow clone).
+ */
+
+import { PragmaError } from "../../../error/index.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Raw entry shape accepted in pragma.config.json `packages` array. */
+export type RawPackageEntry =
+  | string
+  | { readonly name: string; readonly source?: string };
+
+/** Parsed, validated package reference — discriminated by `kind`. */
+export type PackageRef =
+  | { readonly kind: "npm"; readonly pkg: string }
+  | { readonly kind: "file"; readonly pkg: string; readonly path: string }
+  | {
+      readonly kind: "git";
+      readonly pkg: string;
+      readonly url: string;
+      readonly ref: string;
+    };
+
+// ---------------------------------------------------------------------------
+// Parser
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a raw package entry into a typed PackageRef.
+ *
+ * @param entry - String (npm package name) or object with optional source.
+ * @returns Parsed PackageRef.
+ * @throws PragmaError with code CONFIG_ERROR on invalid format.
+ */
+export function parsePackageEntry(entry: RawPackageEntry): PackageRef {
+  if (typeof entry === "string") {
+    return { kind: "npm", pkg: entry };
+  }
+
+  const { name, source } = entry;
+
+  if (typeof name !== "string" || name.length === 0) {
+    throw PragmaError.configError(
+      'Package entry must have a non-empty "name" field.',
+      {
+        recovery: {
+          message:
+            'Each object in the "packages" array requires a "name" string.',
+        },
+      },
+    );
+  }
+
+  if (source === undefined || source === null) {
+    return { kind: "npm", pkg: name };
+  }
+
+  if (typeof source !== "string") {
+    throw PragmaError.configError(
+      `Invalid source for "${name}": expected a string.`,
+    );
+  }
+
+  // file:// — local path override
+  if (source.startsWith("file://")) {
+    const path = source.slice(7);
+    if (path.length === 0) {
+      throw PragmaError.configError(
+        `Invalid source for "${name}": file:// must be followed by a path.`,
+        {
+          recovery: {
+            message: "Example: file:///home/user/code/my-package",
+          },
+        },
+      );
+    }
+    return { kind: "file", pkg: name, path };
+  }
+
+  // git+<protocol>:// — git ref (https, ssh, file)
+  if (source.startsWith("git+")) {
+    const hashIdx = source.indexOf("#");
+    if (hashIdx === -1 || hashIdx === source.length - 1) {
+      throw PragmaError.configError(
+        `Invalid source for "${name}": git URL must include a ref after #.`,
+        {
+          recovery: {
+            message: "Example: git+https://github.com/org/repo.git#main",
+          },
+        },
+      );
+    }
+    const url = source.slice(4, hashIdx); // strip "git+" prefix, keep up to #
+    const ref = source.slice(hashIdx + 1);
+    return { kind: "git", pkg: name, url, ref };
+  }
+
+  throw PragmaError.configError(
+    `Invalid source for "${name}": "${source}". Expected file://, git+https://, git+ssh://, or git+file://.`,
+    {
+      recovery: {
+        message:
+          "Valid formats:\n  file:///absolute/path\n  git+https://host/repo.git#ref\n  git+ssh://git@host/repo.git#ref\n  git+file:///local/bare/repo.git#ref",
+      },
+    },
+  );
+}