@canonical/pragma-cli 0.31.0 → 0.33.0

package/src/kernel/runtime/readEntity.ts

@@ -0,0 +1,83 @@
+/**
+ * Store-backed single-entity read: every triple where a URI is the subject,
+ * grouped by predicate.
+ *
+ * The ONE reader shared by the `graph inspect` CLI verb and the MCP resource
+ * `read` — so a resource read and a `graph inspect` of the same URI return
+ * identical content (the mirror contract). The URI is resolved through the
+ * store's merged prefix map and validated safe for `<iri>` embedding — via
+ * `resolveUri` → `assertSafeIri`, which rejects every IRI-breaking character
+ * (`<>"{}|\^\`` + whitespace) — before it is interpolated, so a prefixed name or
+ * absolute IRI addresses the subject exactly and user input never reaches the
+ * query text raw.
+ *
+ * Reached only behind the lazy store (a `needsStore` verb / a resource read), so
+ * it never lands on the storeless fast path.
+ */
+
+import { PragmaError } from "../error/PragmaError.js";
+import { resolveUri } from "../packs/iri.js";
+import type { PragmaRuntime } from "./types.js";
+
+/** All objects asserted for one predicate on a subject. */
+export interface PredicateGroup {
+  readonly predicate: string;
+  readonly objects: string[];
+}
+
+/** The result of inspecting one subject URI. */
+export interface InspectResult {
+  /** The resolved (full) subject URI. */
+  readonly uri: string;
+  /** Human label from the pack index, when known. */
+  readonly label?: string | null;
+  /** Predicate/object groups, ordered by predicate. */
+  readonly groups: PredicateGroup[];
+}
+
+/**
+ * Read one entity's triples, grouped by predicate.
+ *
+ * @param rt - The runtime (lazy store + query facade).
+ * @param uri - A prefixed name or absolute IRI.
+ * @returns The resolved URI, its index label, and predicate groups.
+ * @throws PragmaError ENTITY_NOT_FOUND when the subject has no triples.
+ * @note Impure — boots the store and queries it.
+ */
+export async function readEntity(
+  rt: Pick<PragmaRuntime, "store" | "query">,
+  uri: string,
+): Promise<InspectResult> {
+  const session = await rt.store.get();
+  const resolved = resolveUri(uri, session.prefixes);
+
+  const result = await rt.query.sparql(
+    `SELECT ?predicate ?object WHERE { <${resolved}> ?predicate ?object } ORDER BY ?predicate ?object`,
+  );
+
+  if (result.type !== "select" || result.bindings.length === 0) {
+    throw PragmaError.notFound("entity", uri, {
+      recovery: {
+        message: "Check the URI, or list known entities.",
+        cli: "pragma graph query 'SELECT ?s WHERE { ?s ?p ?o } LIMIT 10'",
+        mcp: { tool: "graph_query" },
+      },
+    });
+  }
+
+  const groupMap = new Map<string, string[]>();
+  for (const binding of result.bindings) {
+    const predicate = binding.predicate ?? "";
+    const object = binding.object ?? "";
+    const objects = groupMap.get(predicate) ?? [];
+    objects.push(object);
+    groupMap.set(predicate, objects);
+  }
+  const groups = [...groupMap.entries()].map(([predicate, objects]) => ({
+    predicate,
+    objects,
+  }));
+
+  const label = session.index.entities.find((e) => e.uri === resolved)?.label;
+  return { uri: resolved, ...(label != null ? { label } : {}), groups };
+}

package/src/kernel/runtime/refs/gitOps.ts

@@ -0,0 +1,88 @@
+/**
+ * Git operations for cached package clones.
+ *
+ * Ported from the v1 refs domain. Every call is `execFileSync` with the default
+ * `shell: false`, so refs and URLs are passed as argv, never interpolated into
+ * a shell. Authentication is delegated entirely to the user's git client (SSH
+ * keys, credential helpers) — zero custom auth. Shallow clones (`--depth 1`)
+ * keep checkouts cheap.
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+/** 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);
+}
+
+/** Run git in a directory, throwing on non-zero exit. */
+function git(cwd: string, args: readonly string[]): void {
+  execFileSync("git", [...args], { cwd, stdio: "pipe" });
+}
+
+/** Run git and return trimmed stdout. */
+function gitOutput(cwd: string, args: readonly string[]): string {
+  return execFileSync("git", [...args], { cwd, stdio: "pipe" })
+    .toString()
+    .trim();
+}
+
+/**
+ * Clone a repository at a ref into a destination directory (must not exist).
+ *
+ * @param url - Git remote URL.
+ * @param ref - Branch, tag, or commit SHA.
+ * @param dest - Target directory.
+ * @note Impure — runs git, writes the checkout.
+ */
+export function cloneRef(url: string, ref: string, dest: string): void {
+  mkdirSync(dirname(dest), { recursive: true });
+  if (isSha(ref)) {
+    // Shallow clone by SHA is unsupported — init + fetch the commit + checkout.
+    mkdirSync(dest, { recursive: true });
+    git(dest, ["init"]);
+    git(dest, ["fetch", "--depth", "1", url, ref]);
+    git(dest, ["checkout", "FETCH_HEAD"]);
+  } else {
+    execFileSync("git", ["clone", "--depth", "1", "--branch", ref, url, dest], {
+      stdio: "pipe",
+    });
+  }
+}
+
+/**
+ * Fetch a ref into an existing cached clone and check it out.
+ *
+ * @returns The newly resolved HEAD commit.
+ * @note Impure — runs git, updates the checkout.
+ */
+export function fetchRef(url: string, ref: string, dest: string): string {
+  git(dest, ["fetch", "--depth", "1", url, ref]);
+  git(dest, ["checkout", "FETCH_HEAD"]);
+  return gitOutput(dest, ["rev-parse", "HEAD"]);
+}
+
+/** Check out an exact commit in an existing clone (fetching it if needed). */
+export function checkoutCommit(
+  url: string,
+  commit: string,
+  dest: string,
+): void {
+  if (!existsSync(dest)) {
+    cloneRef(url, commit, dest);
+    return;
+  }
+  try {
+    git(dest, ["checkout", commit]);
+  } catch {
+    git(dest, ["fetch", "--depth", "1", url, commit]);
+    git(dest, ["checkout", commit]);
+  }
+}
+
+/** The resolved HEAD commit of a checkout. */
+export function headCommit(dest: string): string {
+  return gitOutput(dest, ["rev-parse", "HEAD"]);
+}

package/src/kernel/runtime/refs/parseRef.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import { redactUrl } from "./parseRef.js";
+
+describe("redactUrl", () => {
+  it("strips user:password userinfo so an inlined token never reaches output", () => {
+    expect(redactUrl("https://alice:ghp_SECRET@github.com/org/repo.git")).toBe(
+      "https://***@github.com/org/repo.git",
+    );
+  });
+
+  it("strips a token-as-username (no colon)", () => {
+    expect(redactUrl("https://ghp_SECRET@github.com/org/repo.git")).toBe(
+      "https://***@github.com/org/repo.git",
+    );
+  });
+
+  it("redacts across a compound scheme (git+https)", () => {
+    expect(redactUrl("git+https://user:tok@host.example/x.git")).toBe(
+      "git+https://***@host.example/x.git",
+    );
+  });
+
+  it("leaves a credential-free URL unchanged", () => {
+    expect(redactUrl("https://github.com/org/repo.git")).toBe(
+      "https://github.com/org/repo.git",
+    );
+  });
+
+  it("does not treat an '@' after the first path slash as userinfo", () => {
+    expect(redactUrl("https://host.example/org/@scope/pkg")).toBe(
+      "https://host.example/org/@scope/pkg",
+    );
+  });
+});

package/src/kernel/runtime/refs/parseRef.ts

@@ -0,0 +1,103 @@
+/**
+ * Parse a config `packages` entry into a typed {@link PackageRef}.
+ *
+ * Ported from the v1 refs domain. Three resolution strategies, discriminated by
+ * `kind`: `npm` (a bare package name, resolved via `require.resolve`), `file`
+ * (a `file://` local path override), and `git` (a `git+<proto>://…#ref` shallow
+ * clone). The `source` string is kept verbatim so the lock records exactly what
+ * the config declared.
+ */
+
+import type { PackageEntry } from "../../config/types.js";
+import { PragmaError } from "../../error/PragmaError.js";
+
+/** A parsed, validated package reference — discriminated by `kind`. */
+export type PackageRef =
+  | { readonly kind: "npm"; readonly pkg: string; readonly source: string }
+  | {
+      readonly kind: "file";
+      readonly pkg: string;
+      readonly path: string;
+      readonly source: string;
+    }
+  | {
+      readonly kind: "git";
+      readonly pkg: string;
+      readonly url: string;
+      readonly ref: string;
+      readonly source: string;
+    };
+
+/**
+ * Parse a config `packages` entry into a {@link PackageRef}.
+ *
+ * @param entry - A bare npm name, or a `{ name, source }` declaration.
+ * @returns The parsed reference (with the verbatim `source`).
+ * @throws PragmaError CONFIG_ERROR on an invalid `source`.
+ */
+export function parsePackageEntry(entry: PackageEntry): PackageRef {
+  if (typeof entry === "string") {
+    return { kind: "npm", pkg: entry, source: entry };
+  }
+
+  const { name, source } = entry;
+  if (typeof name !== "string" || name.length === 0) {
+    throw PragmaError.configError(
+      'Package entry must have a non-empty "name".',
+    );
+  }
+  if (source === undefined) {
+    return { kind: "npm", pkg: name, source: name };
+  }
+
+  if (source.startsWith("file://")) {
+    const path = source.slice("file://".length);
+    if (path.length === 0) {
+      throw PragmaError.configError(
+        `Invalid source for "${name}": file:// must be followed by a path.`,
+      );
+    }
+    return { kind: "file", pkg: name, path, source };
+  }
+
+  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",
+          },
+        },
+      );
+    }
+    return {
+      kind: "git",
+      pkg: name,
+      url: source.slice("git+".length, hashIdx),
+      ref: source.slice(hashIdx + 1),
+      source,
+    };
+  }
+
+  throw PragmaError.configError(
+    `Invalid source for "${name}": "${source}". Expected file://, git+https://, git+ssh://, or git+file://.`,
+  );
+}
+
+/**
+ * Strip any userinfo (`user:pass@` / `token@`) from a URL for display.
+ *
+ * A git source can inline credentials (`git+https://user:TOKEN@host/…`); those
+ * must never reach progress or error output, which lands in stderr logs and —
+ * via `toolError` — MCP-agent-visible responses. Applied only where a URL is
+ * interpolated for a human/agent; `PackageRef.url` keeps the credential verbatim
+ * so git can still authenticate.
+ *
+ * @param url - A URL that may carry userinfo before the host.
+ * @returns The URL with any leading `userinfo@` replaced by `***@`.
+ */
+export function redactUrl(url: string): string {
+  return url.replace(/^([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)[^/@]+@/, "$1***@");
+}

package/src/kernel/runtime/refs/resolve.ts

@@ -0,0 +1,380 @@
+/**
+ * Resolve a {@link PackageRef} to its pinned revision and RDF source contents.
+ *
+ * `file` reads the local path in place; `npm` resolves the installed package
+ * from the project's `node_modules`; `git` clones/fetches into the ref cache
+ * (or, under `--frozen`, checks out exactly the lock's pinned commit and never
+ * advances). Each package contributes its `definitions/**` and `data/**` TTL
+ * files, labelled by a stable `pkg/relative-path` so the pack's content hash is
+ * machine-independent. Reached only from the `sources update` Task body.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, relative } from "node:path";
+import { RECOVERY_CLI_PREFIX } from "../../../constants.js";
+import { PragmaError } from "../../error/PragmaError.js";
+import { cliRecovery } from "../../error/recovery.js";
+import { refsCacheDir } from "../paths.js";
+import { checkoutCommit, cloneRef, fetchRef, headCommit } from "./gitOps.js";
+import { type PackageRef, redactUrl } from "./parseRef.js";
+
+/** A resolved package: its pinned revision and labelled RDF sources. */
+export interface ResolvedPackage {
+  readonly name: string;
+  /** The config `packages` source ref, verbatim. */
+  readonly source: string;
+  /** The resolved commit / version / absolute path. */
+  readonly resolved: string;
+  /**
+   * The package's on-disk root — the local `file:` path, the npm install dir, or
+   * the git clone dir. Everything the package ships lives under it, so
+   * `sources update` can also discover a package's `skills/` (U10) from here.
+   */
+  readonly root: string;
+  /** The labelled RDF sources (path label + content). */
+  readonly sources: { readonly path: string; readonly content: string }[];
+}
+
+/** Options for a resolution: whether to honour a pinned commit (`--frozen`). */
+export interface ResolveOptions {
+  readonly cwd: string;
+  readonly frozen: boolean;
+  /** The lock's pinned revision for this package (used under `--frozen`). */
+  readonly pinned?: string;
+}
+
+/** The package subdirectories scanned for `.ttl` sources. */
+const TTL_DIRS = ["definitions", "data"];
+
+/** Sanitize a ref for use as a cache path segment. */
+const sanitize = (value: string): string => value.replace(/[/\\:*?"<>|]/g, "_");
+
+/** A concise reason from a thrown subprocess/parse error: prefer captured
+ * stderr (git writes the real reason there under `stdio: "pipe"`), else the
+ * message. Used to name WHY a resolve failed without dumping a raw stack. */
+function errorDetail(error: unknown): string {
+  if (error && typeof error === "object") {
+    const { stderr, message } = error as {
+      stderr?: unknown;
+      message?: unknown;
+    };
+    if (stderr != null) {
+      const text = String(stderr).trim();
+      if (text) return text;
+    }
+    if (typeof message === "string" && message.trim()) return message.trim();
+  }
+  return String(error);
+}
+
+/** Recursively collect `*.ttl` files under a directory (a manual walk — the
+ * compiled binary's node:fs globSync mishandles `**`, so we avoid it). */
+function walkTtl(
+  dir: string,
+  base: string,
+  label: string,
+  out: { path: string; content: string }[],
+): void {
+  if (!existsSync(dir)) return;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    // Skip hidden entries (dot-prefixed): editor/partial/generated artifacts
+    // like `.modifier.dark.ttl`, and tooling dirs like `.git`, are never
+    // intended graph sources — and ingesting them ships malformed RDF into the
+    // build (a `.`-prefixed Turtle local name isn't even valid).
+    if (entry.name.startsWith(".")) continue;
+    const full = join(dir, entry.name);
+    // Resolve symlinks: pnpm / workspace trees link their sources, but
+    // `Dirent.isFile`/`isDirectory` are BOTH false for a symlink — so a
+    // symlinked `.ttl` was silently skipped (L6). Follow the link to recover a
+    // symlinked FILE, but NEVER recurse into a symlinked DIRECTORY: a symlink
+    // cycle (a link to an ancestor dir) would recurse without bound — a
+    // stack-overflow RangeError surfacing as an INTERNAL "please report" — and a
+    // linked directory could pull `.ttl` from OUTSIDE the package root. Linking
+    // individual source files (all L6 needs) stays supported; a dangling link is
+    // skipped, not fatal.
+    let isDir = entry.isDirectory();
+    let isFile = entry.isFile();
+    if (entry.isSymbolicLink()) {
+      try {
+        isFile = statSync(full).isFile();
+        isDir = false;
+      } catch {
+        continue;
+      }
+    }
+    if (isDir) {
+      walkTtl(full, base, label, out);
+    } else if (isFile && entry.name.endsWith(".ttl")) {
+      out.push({
+        path: `${label}/${relative(base, full)}`,
+        content: readFileSync(full, "utf-8"),
+      });
+    }
+  }
+}
+
+/** Read a package's `definitions/**` and `data/**` TTL, with stable labels. */
+function readTtlSources(
+  rootDir: string,
+  label: string,
+): { path: string; content: string }[] {
+  const sources: { path: string; content: string }[] = [];
+  for (const sub of TTL_DIRS) {
+    walkTtl(join(rootDir, sub), rootDir, label, sources);
+  }
+  sources.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  return sources;
+}
+
+/**
+ * A Turtle/SPARQL prefix prologue declaration: `@prefix ex: <iri> .` or the
+ * keyword-form `PREFIX ex: <iri>`. Both are legal in Turtle 1.1; the keyword is
+ * case-insensitive and the leading `@` is optional, so `@?prefix` with the `i`
+ * flag covers every spelling. The label group requires at least one character,
+ * so the default-namespace form (`@prefix : <iri>`) is skipped — its `:local`
+ * tokens are not the named-prefix contract the index freezes.
+ */
+const PREFIX_DECL = /(?:^|\s)@?prefix\s+([^\s:]+):\s*<([^>]*)>/gi;
+
+/**
+ * Harvest a package's own `@prefix` / `PREFIX` declarations from its TTL text.
+ *
+ * ke's `createStore` does NOT fold parsed-Turtle prefixes into `store.prefixes`
+ * (TTL `@prefix` applies only within a file during parsing), so a package's
+ * namespaces are invisible to the index unless we lift them out of the source
+ * ourselves. The returned map (label → namespace IRI) is merged BELOW config
+ * precedence so the pack's own names compact to `pfx:Local` in the index.
+ *
+ * @param sources - The package's labelled RDF sources.
+ * @returns A prefix map of every named declaration found (last wins on clash).
+ */
+export function harvestPrefixes(
+  sources: readonly { readonly content: string }[],
+): Record<string, string> {
+  const prefixes: Record<string, string> = {};
+  for (const { content } of sources) {
+    for (const match of content.matchAll(PREFIX_DECL)) {
+      const [, label, iri] = match;
+      if (label !== undefined && iri !== undefined) prefixes[label] = iri;
+    }
+  }
+  return prefixes;
+}
+
+/** One `@prefix` clash: a label declared with two or more distinct IRIs. */
+export interface PrefixClash {
+  readonly label: string;
+  /** The distinct IRIs bound to the label, in first-seen order. */
+  readonly iris: readonly string[];
+}
+
+/**
+ * Detect `@prefix` label clashes across a set of sources.
+ *
+ * {@link harvestPrefixes} resolves clashes last-wins (Turtle's own rule),
+ * silently compacting the losing package's URIs to the wrong prefix (or to full
+ * IRIs). This surfaces the clashes so `sources update` can warn (A5): a label
+ * bound to two or more distinct IRIs. Harmless same-label/same-IRI
+ * redeclarations (the common case) are NOT clashes. Result is sorted by label
+ * so the warnings are deterministic.
+ *
+ * @param sources - The packages' labelled RDF sources.
+ * @returns One entry per clashing label, each with its distinct IRIs.
+ */
+export function detectPrefixClashes(
+  sources: readonly { readonly content: string }[],
+): PrefixClash[] {
+  const byLabel = new Map<string, string[]>();
+  for (const { content } of sources) {
+    for (const match of content.matchAll(PREFIX_DECL)) {
+      const [, label, iri] = match;
+      if (label === undefined || iri === undefined) continue;
+      const iris = byLabel.get(label) ?? [];
+      if (!iris.includes(iri)) iris.push(iri);
+      byLabel.set(label, iris);
+    }
+  }
+  const clashes: PrefixClash[] = [];
+  for (const [label, iris] of byLabel) {
+    if (iris.length > 1) clashes.push({ label, iris });
+  }
+  clashes.sort((a, b) => (a.label < b.label ? -1 : a.label > b.label ? 1 : 0));
+  return clashes;
+}
+
+/**
+ * Locate a package's `package.json` from the project.
+ *
+ * The direct `require.resolve("<pkg>/package.json")` throws
+ * `ERR_PACKAGE_PATH_NOT_EXPORTED` for a package whose `exports` map does not
+ * expose `./package.json` (common with modern packages) — which would be
+ * misreported as "not installed". So on failure it falls back to resolving the
+ * package entry and walking up to the `package.json` whose `name` matches.
+ *
+ * @param require - A `createRequire` bound to the project directory.
+ * @param pkg - The package name.
+ * @returns The absolute `package.json` path, or `undefined` when not installed.
+ */
+export function resolvePackageJson(
+  require: ReturnType<typeof createRequire>,
+  pkg: string,
+): string | undefined {
+  try {
+    return require.resolve(`${pkg}/package.json`);
+  } catch {
+    // `exports` may not expose ./package.json — resolve the entry and walk up.
+  }
+  let current: string;
+  try {
+    current = dirname(require.resolve(pkg));
+  } catch {
+    return undefined;
+  }
+  for (let depth = 0; depth < 64; depth++) {
+    const candidate = join(current, "package.json");
+    if (existsSync(candidate)) {
+      try {
+        const parsed = JSON.parse(readFileSync(candidate, "utf-8")) as {
+          name?: unknown;
+        };
+        if (parsed.name === pkg) return candidate;
+      } catch {
+        // Unreadable or non-JSON — keep walking up.
+      }
+    }
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return undefined;
+}
+
+/**
+ * Resolve a package reference to its revision and RDF sources.
+ *
+ * @param ref - The parsed package reference.
+ * @param options - The cwd, frozen flag, and any pinned revision.
+ * @returns The resolved package.
+ * @throws PragmaError on a missing file path or unresolvable npm package.
+ * @throws PragmaError under `--frozen` when the package has no lock entry.
+ * @note Impure — may clone/fetch git, reads TTL from disk.
+ */
+export async function resolvePackage(
+  ref: PackageRef,
+  options: ResolveOptions,
+): Promise<ResolvedPackage> {
+  // `--frozen` means "reproduce the locked state exactly". A configured package
+  // with no lock entry has nothing to reproduce, so refuse rather than silently
+  // resolving it fresh (which would advance the very state the lock pins).
+  if (options.frozen && options.pinned === undefined) {
+    throw PragmaError.configError(
+      `Cannot resolve "${ref.pkg}" under --frozen: it has no entry in the lock.`,
+      {
+        recovery: cliRecovery(
+          `${RECOVERY_CLI_PREFIX}sources update`,
+          "Update the lock without --frozen, then commit it.",
+        ),
+      },
+    );
+  }
+
+  switch (ref.kind) {
+    case "file": {
+      if (!existsSync(ref.path)) {
+        throw PragmaError.configError(
+          `Package "${ref.pkg}" path not found: ${ref.path}.`,
+        );
+      }
+      return {
+        name: ref.pkg,
+        source: ref.source,
+        resolved: ref.path,
+        root: ref.path,
+        sources: readTtlSources(ref.path, ref.pkg),
+      };
+    }
+
+    case "npm": {
+      const require = createRequire(join(options.cwd, "noop.js"));
+      const pkgJsonPath = resolvePackageJson(require, ref.pkg);
+      if (pkgJsonPath === undefined) {
+        throw PragmaError.configError(
+          `Package "${ref.pkg}" is not installed. Add it to the project.`,
+        );
+      }
+      const dir = dirname(pkgJsonPath);
+      let version: string;
+      try {
+        version =
+          (JSON.parse(readFileSync(pkgJsonPath, "utf-8")).version as string) ??
+          "0.0.0";
+      } catch (error) {
+        // A malformed `package.json` for an otherwise-installed package: name it
+        // as a data error, not an INTERNAL_ERROR "please report this issue".
+        throw PragmaError.configError(
+          `Package "${ref.pkg}" has an invalid package.json (${pkgJsonPath}): ${errorDetail(error)}`,
+        );
+      }
+      return {
+        name: ref.pkg,
+        source: ref.source,
+        resolved: version,
+        root: dir,
+        sources: readTtlSources(dir, ref.pkg),
+      };
+    }
+
+    case "git": {
+      const useCommit = options.frozen && options.pinned;
+      const dir = join(
+        refsCacheDir(),
+        sanitize(ref.pkg),
+        sanitize(useCommit ? (options.pinned as string) : ref.ref),
+      );
+      let resolved: string;
+      try {
+        if (useCommit) {
+          checkoutCommit(ref.url, options.pinned as string, dir);
+          resolved = options.pinned as string;
+        } else if (existsSync(dir)) {
+          resolved = fetchRef(ref.url, ref.ref, dir);
+        } else {
+          cloneRef(ref.url, ref.ref, dir);
+          resolved = headCommit(dir);
+        }
+      } catch (error) {
+        // A git clone/fetch/checkout failed — an unreachable remote, a moved or
+        // deleted ref, an auth/credential problem, or (under --frozen) a pinned
+        // commit that is gone. Name the package + ref with git's own reason so
+        // it reads as a fixable data/reproducibility error, not INTERNAL_ERROR.
+        throw useCommit
+          ? PragmaError.configError(
+              `Cannot reproduce "${ref.pkg}" under --frozen: commit ${options.pinned} could not be checked out from ${redactUrl(ref.url)}. ${errorDetail(error)}`,
+              {
+                recovery: {
+                  message:
+                    "The pinned commit may have been force-pushed away or the remote is unreachable. Restore access to it, or re-run `pragma sources update` without --frozen to re-pin.",
+                },
+              },
+            )
+          : PragmaError.configError(
+              `Cannot resolve "${ref.pkg}" from ${redactUrl(ref.url)}#${ref.ref}: ${errorDetail(error)}`,
+              {
+                recovery: {
+                  message:
+                    "Check the git URL and ref, your network, and your git credentials, then re-run the update.",
+                },
+              },
+            );
+      }
+      return {
+        name: ref.pkg,
+        source: ref.source,
+        resolved,
+        root: dir,
+        sources: readTtlSources(dir, ref.pkg),
+      };
+    }
+  }
+}