@canonical/pragma-cli 0.30.0 → 0.32.0

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

@@ -1,114 +0,0 @@
-/**
- * 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",
-      },
-    },
-  );
-}

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

@@ -1,98 +0,0 @@
-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

@@ -1,91 +0,0 @@
-/**
- * Cross-platform path resolution for pragma cache, config, and data.
- *
- * Respects XDG Base Directory Specification:
- * - XDG_CACHE_HOME for cache (default: ~/.cache)
- * - XDG_CONFIG_HOME for global config (default: ~/.config)
- * - XDG_DATA_HOME for persistent data (default: ~/.local/share)
- *
- * 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");
-}
-
-/**
- * Root directory for pragma persistent data (extracted skills, etc.).
- *
- * Resolution order:
- * 1. XDG_DATA_HOME/pragma (XDG spec)
- * 2. ~/.local/share/pragma (default)
- */
-export function dataRoot(): string {
-  const xdg = process.env.XDG_DATA_HOME;
-  const base = xdg ?? join(homedir(), ".local", "share");
-  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);
-}
-
-/**
- * Root directory for query trace logs.
- *
- * Resolution order:
- * 1. PRAGMA_TRACE_DIR environment variable (CI/testing override)
- * 2. XDG_DATA_HOME/pragma/traces (default)
- */
-export function traceDir(): string {
-  if (process.env.PRAGMA_TRACE_DIR) {
-    return process.env.PRAGMA_TRACE_DIR;
-  }
-  return join(dataRoot(), "traces");
-}
-
-/**
- * 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

@@ -1,63 +0,0 @@
-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

@@ -1,37 +0,0 @@
-/**
- * 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

@@ -1,167 +0,0 @@
-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 3 defaults are git refs
-    expect(results).toHaveLength(3);
-    for (const r of results) {
-      // Each result is either cloned, up-to-date, or error (network)
-      expect(["cloned", "updated", "up-to-date", "error"]).toContain(r.kind);
-    }
-  });
-});