@canonical/pragma-cli 0.25.0 → 0.26.0

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

@@ -0,0 +1,98 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { cacheRoot, gitCacheDir, globalConfigDir } from "./paths.js";
+
+describe("cacheRoot", () => {
+  const origEnv = { ...process.env };
+
+  afterEach(() => {
+    process.env = { ...origEnv };
+  });
+
+  it("uses PRAGMA_CACHE_DIR when set", () => {
+    process.env.PRAGMA_CACHE_DIR = "/tmp/pragma-test-cache";
+    expect(cacheRoot()).toBe("/tmp/pragma-test-cache");
+  });
+
+  it("uses XDG_CACHE_HOME/pragma when set", () => {
+    delete process.env.PRAGMA_CACHE_DIR;
+    process.env.XDG_CACHE_HOME = "/tmp/xdg-cache";
+    expect(cacheRoot()).toBe(join("/tmp/xdg-cache", "pragma"));
+  });
+
+  it("PRAGMA_CACHE_DIR takes precedence over XDG_CACHE_HOME", () => {
+    process.env.PRAGMA_CACHE_DIR = "/tmp/pragma-override";
+    process.env.XDG_CACHE_HOME = "/tmp/xdg-cache";
+    expect(cacheRoot()).toBe("/tmp/pragma-override");
+  });
+
+  it("falls back to ~/.cache/pragma", () => {
+    delete process.env.PRAGMA_CACHE_DIR;
+    delete process.env.XDG_CACHE_HOME;
+    expect(cacheRoot()).toBe(join(homedir(), ".cache", "pragma"));
+  });
+});
+
+describe("globalConfigDir", () => {
+  const origEnv = { ...process.env };
+
+  afterEach(() => {
+    process.env = { ...origEnv };
+  });
+
+  it("uses XDG_CONFIG_HOME/pragma when set", () => {
+    process.env.XDG_CONFIG_HOME = "/tmp/xdg-config";
+    expect(globalConfigDir()).toBe(join("/tmp/xdg-config", "pragma"));
+  });
+
+  it("falls back to ~/.config/pragma", () => {
+    delete process.env.XDG_CONFIG_HOME;
+    expect(globalConfigDir()).toBe(join(homedir(), ".config", "pragma"));
+  });
+});
+
+describe("gitCacheDir", () => {
+  const origEnv = { ...process.env };
+
+  beforeEach(() => {
+    process.env.PRAGMA_CACHE_DIR = "/tmp/pragma-test-cache";
+  });
+
+  afterEach(() => {
+    process.env = { ...origEnv };
+  });
+
+  it("returns cache path for a package and ref", () => {
+    expect(gitCacheDir("@canonical/design-system", "main")).toBe(
+      join(
+        "/tmp/pragma-test-cache",
+        "refs",
+        "@canonical/design-system",
+        "main",
+      ),
+    );
+  });
+
+  it("sanitizes slashes in ref", () => {
+    expect(gitCacheDir("@canonical/design-system", "feature/branch")).toBe(
+      join(
+        "/tmp/pragma-test-cache",
+        "refs",
+        "@canonical/design-system",
+        "feature_branch",
+      ),
+    );
+  });
+
+  it("sanitizes colons in ref", () => {
+    expect(gitCacheDir("@canonical/design-system", "v1:beta")).toBe(
+      join(
+        "/tmp/pragma-test-cache",
+        "refs",
+        "@canonical/design-system",
+        "v1_beta",
+      ),
+    );
+  });
+});

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

@@ -0,0 +1,63 @@
+/**
+ * Cross-platform path resolution for pragma cache and global config.
+ *
+ * Respects XDG Base Directory Specification:
+ * - XDG_CACHE_HOME for cache (default: ~/.cache)
+ * - XDG_CONFIG_HOME for global config (default: ~/.config)
+ *
+ * Override via PRAGMA_CACHE_DIR for CI and testing.
+ * Uses os.homedir() for macOS/WSL/Linux portability.
+ */
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Root directory for pragma cache data.
+ *
+ * Resolution order:
+ * 1. PRAGMA_CACHE_DIR environment variable (CI/testing override)
+ * 2. XDG_CACHE_HOME/pragma (XDG spec)
+ * 3. ~/.cache/pragma (default)
+ */
+export function cacheRoot(): string {
+  if (process.env.PRAGMA_CACHE_DIR) {
+    return process.env.PRAGMA_CACHE_DIR;
+  }
+  const xdg = process.env.XDG_CACHE_HOME;
+  const base = xdg ?? join(homedir(), ".cache");
+  return join(base, "pragma");
+}
+
+/**
+ * Root directory for pragma global configuration.
+ *
+ * Resolution order:
+ * 1. XDG_CONFIG_HOME/pragma (XDG spec)
+ * 2. ~/.config/pragma (default)
+ */
+export function globalConfigDir(): string {
+  const xdg = process.env.XDG_CONFIG_HOME;
+  const base = xdg ?? join(homedir(), ".config");
+  return join(base, "pragma");
+}
+
+/**
+ * Cache directory for a specific git-ref-resolved package.
+ *
+ * @param pkg - Package name (e.g., "@canonical/design-system").
+ * @param ref - Git ref (e.g., "main", "v0.3.0", "abc1234").
+ * @returns Absolute path to the cached clone directory.
+ */
+export function gitCacheDir(pkg: string, ref: string): string {
+  const sanitizedRef = sanitizeRef(ref);
+  return join(cacheRoot(), "refs", pkg, sanitizedRef);
+}
+
+/**
+ * Sanitize a git ref for use as a directory name.
+ * Replaces characters that are invalid or confusing in path segments.
+ */
+function sanitizeRef(ref: string): string {
+  return ref.replace(/[/\\:*?"<>|]/g, "_");
+}

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

@@ -0,0 +1,63 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import readGlobalRefs from "./readGlobalRefs.js";
+
+describe("readGlobalRefs", () => {
+  let tmpDir: string;
+  const origEnv = { ...process.env };
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "pragma-global-refs-"));
+    // Point XDG_CONFIG_HOME to our temp dir so globalConfigDir() resolves there
+    process.env.XDG_CONFIG_HOME = tmpDir;
+  });
+
+  afterEach(() => {
+    process.env = { ...origEnv };
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("returns empty array when refs.json does not exist", () => {
+    expect(readGlobalRefs()).toEqual([]);
+  });
+
+  it("returns empty array when refs.json is malformed JSON", () => {
+    const dir = join(tmpDir, "pragma");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "refs.json"), "{bad json");
+    expect(readGlobalRefs()).toEqual([]);
+  });
+
+  it("returns empty array when packages field is missing", () => {
+    const dir = join(tmpDir, "pragma");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "refs.json"), "{}");
+    expect(readGlobalRefs()).toEqual([]);
+  });
+
+  it("returns empty array when packages is not an array", () => {
+    const dir = join(tmpDir, "pragma");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(
+      join(dir, "refs.json"),
+      JSON.stringify({ packages: "not-array" }),
+    );
+    expect(readGlobalRefs()).toEqual([]);
+  });
+
+  it("returns packages array from valid refs.json", () => {
+    const dir = join(tmpDir, "pragma");
+    mkdirSync(dir, { recursive: true });
+    const packages = [
+      "@canonical/design-system",
+      {
+        name: "@canonical/code-standards",
+        source: "file:///home/user/code/code-standards",
+      },
+    ];
+    writeFileSync(join(dir, "refs.json"), JSON.stringify({ packages }));
+    expect(readGlobalRefs()).toEqual(packages);
+  });
+});

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

@@ -0,0 +1,37 @@
+/**
+ * Read global package refs from ~/.config/pragma/refs.json.
+ *
+ * Global refs provide user-level overrides that apply to all projects.
+ * Project-level `pragma.config.json` overrides global refs.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { RawPackageEntry } from "./parseRef.js";
+import { globalConfigDir } from "./paths.js";
+
+/**
+ * Read global package references.
+ *
+ * @returns The `packages` array from `~/.config/pragma/refs.json`, or
+ *          an empty array when the file is missing or malformed.
+ */
+export default function readGlobalRefs(): ReadonlyArray<RawPackageEntry> {
+  const refsPath = join(globalConfigDir(), "refs.json");
+
+  let raw: string;
+  try {
+    raw = readFileSync(refsPath, "utf-8");
+  } catch {
+    return [];
+  }
+
+  try {
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    const packages = parsed.packages;
+    if (!Array.isArray(packages)) return [];
+    return packages as RawPackageEntry[];
+  } catch {
+    return [];
+  }
+}

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

@@ -0,0 +1,164 @@
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import updateRefs from "./updateRefs.js";
+
+describe("updateRefs", () => {
+  let tmpDir: string;
+  let projectDir: string;
+  let bareRepo: string;
+  const origEnv = { ...process.env };
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "pragma-update-refs-"));
+    projectDir = join(tmpDir, "project");
+    mkdirSync(projectDir, { recursive: true });
+
+    // Point cache to temp dir
+    process.env.PRAGMA_CACHE_DIR = join(tmpDir, "cache");
+    // No global refs
+    process.env.XDG_CONFIG_HOME = join(tmpDir, "no-global-config");
+
+    // Create a bare git repo for testing
+    bareRepo = join(tmpDir, "origin.git");
+    execFileSync("git", ["init", "--bare", "-b", "main", bareRepo], {
+      stdio: "pipe",
+    });
+
+    const workDir = join(tmpDir, "work");
+    execFileSync("git", ["clone", bareRepo, workDir], { stdio: "pipe" });
+    execFileSync("git", ["-C", workDir, "config", "user.email", "t@t.com"], {
+      stdio: "pipe",
+    });
+    execFileSync("git", ["-C", workDir, "config", "user.name", "T"], {
+      stdio: "pipe",
+    });
+    execFileSync(
+      "git",
+      ["-C", workDir, "commit", "--allow-empty", "-m", "init"],
+      { stdio: "pipe" },
+    );
+    execFileSync("git", ["-C", workDir, "push", "origin", "main"], {
+      stdio: "pipe",
+    });
+    rmSync(workDir, { recursive: true, force: true });
+  });
+
+  afterEach(() => {
+    process.env = { ...origEnv };
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("clones a git ref on first run", async () => {
+    writeFileSync(
+      join(projectDir, "pragma.config.json"),
+      JSON.stringify({
+        packages: [
+          {
+            name: "@test/pkg",
+            source: `git+file://${bareRepo}#main`,
+          },
+        ],
+      }),
+    );
+
+    const results = await updateRefs({ cwd: projectDir });
+    expect(results).toHaveLength(1);
+    expect(results[0].kind).toBe("cloned");
+    expect(results[0].pkg).toBe("@test/pkg");
+  });
+
+  it("reports up-to-date on second run without changes", async () => {
+    writeFileSync(
+      join(projectDir, "pragma.config.json"),
+      JSON.stringify({
+        packages: [
+          {
+            name: "@test/pkg",
+            source: `git+file://${bareRepo}#main`,
+          },
+        ],
+      }),
+    );
+
+    await updateRefs({ cwd: projectDir });
+    const results = await updateRefs({ cwd: projectDir });
+    expect(results).toHaveLength(1);
+    expect(results[0].kind).toBe("up-to-date");
+  });
+
+  it("reports ok for file:// ref pointing to existing path", async () => {
+    const localPkg = join(tmpDir, "local-pkg");
+    mkdirSync(localPkg, { recursive: true });
+
+    writeFileSync(
+      join(projectDir, "pragma.config.json"),
+      JSON.stringify({
+        packages: [{ name: "@test/local", source: `file://${localPkg}` }],
+      }),
+    );
+
+    const results = await updateRefs({ cwd: projectDir });
+    expect(results).toHaveLength(1);
+    expect(results[0].kind).toBe("ok");
+  });
+
+  it("reports error for file:// ref pointing to missing path", async () => {
+    writeFileSync(
+      join(projectDir, "pragma.config.json"),
+      JSON.stringify({
+        packages: [
+          { name: "@test/missing", source: "file:///nonexistent/path" },
+        ],
+      }),
+    );
+
+    const results = await updateRefs({ cwd: projectDir });
+    expect(results).toHaveLength(1);
+    expect(results[0].kind).toBe("error");
+  });
+
+  it("skips npm packages", async () => {
+    writeFileSync(
+      join(projectDir, "pragma.config.json"),
+      JSON.stringify({
+        packages: ["@canonical/design-system"],
+      }),
+    );
+
+    const results = await updateRefs({ cwd: projectDir });
+    expect(results).toHaveLength(1);
+    expect(results[0].kind).toBe("skipped");
+  });
+
+  it("filters by --package flag", async () => {
+    writeFileSync(
+      join(projectDir, "pragma.config.json"),
+      JSON.stringify({
+        packages: [
+          "@canonical/design-system",
+          {
+            name: "@test/pkg",
+            source: `git+file://${bareRepo}#main`,
+          },
+        ],
+      }),
+    );
+
+    const results = await updateRefs({
+      cwd: projectDir,
+      package: "@test/pkg",
+    });
+    expect(results).toHaveLength(1);
+    expect(results[0].pkg).toBe("@test/pkg");
+  });
+
+  it("uses defaults when no config exists", async () => {
+    const results = await updateRefs({ cwd: projectDir });
+    // All 4 defaults are npm, so all skipped
+    expect(results.every((r) => r.kind === "skipped")).toBe(true);
+    expect(results).toHaveLength(4);
+  });
+});

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

@@ -0,0 +1,215 @@
+/**
+ * Update operation: fetch/clone git refs into the local cache.
+ *
+ * Reads project + global config, merges, and for each git ref either
+ * clones (first time) or fetches (subsequent). Reports per-package status.
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { readConfig } from "#config";
+import { DEFAULT_PACKAGES } from "../../shared/packages.js";
+import { cloneRef, fetchRef, pruneCache } from "./gitOps.js";
+import type { PackageRef, RawPackageEntry } from "./parseRef.js";
+import { parsePackageEntry } from "./parseRef.js";
+import { cacheRoot, gitCacheDir } from "./paths.js";
+import readGlobalRefs from "./readGlobalRefs.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface UpdateResult {
+  readonly pkg: string;
+  readonly kind:
+    | "cloned"
+    | "updated"
+    | "up-to-date"
+    | "ok"
+    | "skipped"
+    | "error";
+  readonly detail: string;
+}
+
+export interface UpdateRefsOptions {
+  /** Working directory for reading project config. */
+  cwd: string;
+  /** Update only this package (by name). */
+  package?: string;
+  /** Remove orphaned cache directories. */
+  prune?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Operation
+// ---------------------------------------------------------------------------
+
+/**
+ * Update cached git refs.
+ *
+ * For each configured package:
+ * - git refs: clone or fetch into cache
+ * - file refs: verify the path exists
+ * - npm refs: skip (nothing to update)
+ */
+export default async function updateRefs(
+  options: UpdateRefsOptions,
+): Promise<UpdateResult[]> {
+  const config = readConfig(options.cwd);
+  const refs = mergeEntries(config.packages);
+  const results: UpdateResult[] = [];
+
+  for (const ref of refs) {
+    if (options.package && ref.pkg !== options.package) continue;
+
+    switch (ref.kind) {
+      case "git": {
+        const dest = gitCacheDir(ref.pkg, ref.ref);
+        try {
+          if (existsSync(dest)) {
+            const { updated, oldHead, newHead } = fetchRef(
+              ref.url,
+              ref.ref,
+              dest,
+            );
+            results.push({
+              pkg: ref.pkg,
+              kind: updated ? "updated" : "up-to-date",
+              detail: updated
+                ? `${oldHead.slice(0, 7)} → ${newHead.slice(0, 7)}`
+                : `at ${newHead.slice(0, 7)}`,
+            });
+          } else {
+            cloneRef(ref.url, ref.ref, dest);
+            results.push({
+              pkg: ref.pkg,
+              kind: "cloned",
+              detail: `${ref.url}#${ref.ref}`,
+            });
+          }
+        } catch (err) {
+          results.push({
+            pkg: ref.pkg,
+            kind: "error",
+            detail: err instanceof Error ? err.message : String(err),
+          });
+        }
+        break;
+      }
+
+      case "file": {
+        results.push({
+          pkg: ref.pkg,
+          kind: existsSync(ref.path) ? "ok" : "error",
+          detail: existsSync(ref.path)
+            ? `path exists: ${ref.path}`
+            : `path not found: ${ref.path}`,
+        });
+        break;
+      }
+
+      case "npm": {
+        results.push({
+          pkg: ref.pkg,
+          kind: "skipped",
+          detail: "using npm (no ref configured)",
+        });
+        break;
+      }
+    }
+  }
+
+  if (options.prune) {
+    const pruned = pruneOrphanedCaches(refs);
+    for (const dir of pruned) {
+      results.push({
+        pkg: "(orphan)",
+        kind: "ok",
+        detail: `pruned: ${dir}`,
+      });
+    }
+  }
+
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Merge global + project entries, parse into PackageRef[]. */
+function mergeEntries(
+  projectPackages?: ReadonlyArray<RawPackageEntry>,
+): PackageRef[] {
+  const globalEntries = readGlobalRefs();
+
+  if (
+    (!projectPackages || projectPackages.length === 0) &&
+    globalEntries.length === 0
+  ) {
+    return DEFAULT_PACKAGES.map((pkg) => parsePackageEntry(pkg));
+  }
+
+  const merged = new Map<string, RawPackageEntry>();
+
+  for (const pkg of DEFAULT_PACKAGES) {
+    merged.set(pkg, pkg);
+  }
+  for (const entry of globalEntries) {
+    const name = typeof entry === "string" ? entry : entry.name;
+    merged.set(name, entry);
+  }
+  if (projectPackages) {
+    merged.clear();
+    for (const entry of projectPackages) {
+      const name = typeof entry === "string" ? entry : entry.name;
+      merged.set(name, entry);
+    }
+  }
+
+  return [...merged.values()].map(parsePackageEntry);
+}
+
+/**
+ * Remove cache directories that don't match any configured git ref.
+ * Returns list of removed directories.
+ */
+function pruneOrphanedCaches(refs: PackageRef[]): string[] {
+  const validDirs = new Set(
+    refs
+      .filter(
+        (r): r is Extract<PackageRef, { kind: "git" }> => r.kind === "git",
+      )
+      .map((r) => gitCacheDir(r.pkg, r.ref)),
+  );
+
+  const refsDir = join(cacheRoot(), "refs");
+  if (!existsSync(refsDir)) return [];
+
+  const pruned: string[] = [];
+
+  // Walk two levels: @scope/package/ref/
+  for (const scope of safeReaddir(refsDir)) {
+    const scopeDir = join(refsDir, scope);
+    for (const pkg of safeReaddir(scopeDir)) {
+      const pkgDir = join(scopeDir, pkg);
+      for (const ref of safeReaddir(pkgDir)) {
+        const refDir = join(pkgDir, ref);
+        if (!validDirs.has(refDir)) {
+          pruneCache(refDir);
+          pruned.push(refDir);
+        }
+      }
+    }
+  }
+
+  return pruned;
+}
+
+function safeReaddir(dir: string): string[] {
+  try {
+    return readdirSync(dir);
+  } catch {
+    return [];
+  }
+}