@canonical/pragma-cli 0.30.0 → 0.32.0

package/src/kernel/runtime/lock.ts

@@ -0,0 +1,90 @@
+/**
+ * The project lock — `pragma.lock.json`, committed at the project root.
+ *
+ * It pins the single combined pack the store boots from: `contentHash` names
+ * the pack's cache directory, and `packs[]` records the resolved provenance of
+ * every configured source (so `sources status` reports it and a `--frozen`
+ * update re-resolves to exactly these commits). Serialization is canonical —
+ * fixed field order, packs sorted by name, one trailing newline — so a
+ * `--frozen` update that changes nothing rewrites a byte-identical file.
+ *
+ * Pure: zod + fs only, no store code, so both the storeless `sources status`
+ * verb and the store-boot decision table read it without booting oxigraph.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { z } from "zod";
+import { lockPath } from "./paths.js";
+
+/** One resolved source's provenance in the lock. */
+export const lockPackageSchema = z.object({
+  /** Package name (config `packages` entry name / npm name). */
+  name: z.string(),
+  /** The config `packages` source ref, verbatim (e.g. `git+https://…#main`). */
+  source: z.string(),
+  /** The resolved commit / version / absolute path this ref pinned to. */
+  resolved: z.string(),
+  /** ISO timestamp the ref was resolved. */
+  resolvedAt: z.string(),
+});
+
+/** The lock document. */
+export const pragmaLockSchema = z.object({
+  version: z.literal(1),
+  /** The combined pack's content hash — names its cache directory. */
+  contentHash: z.string(),
+  packs: z.array(lockPackageSchema),
+});
+
+/** One resolved source's provenance in the lock. */
+export type PragmaLockPackage = z.infer<typeof lockPackageSchema>;
+/** The parsed lock document. */
+export type PragmaLock = z.infer<typeof pragmaLockSchema>;
+
+/**
+ * Read and validate the lock for a working directory.
+ *
+ * @param cwd - The project directory.
+ * @returns The parsed lock, or `undefined` when absent or invalid.
+ * @note Impure — reads from disk.
+ */
+export function readLock(cwd: string): PragmaLock | undefined {
+  const path = lockPath(cwd);
+  if (!existsSync(path)) return undefined;
+  try {
+    return pragmaLockSchema.parse(JSON.parse(readFileSync(path, "utf-8")));
+  } catch {
+    return undefined;
+  }
+}
+
+/** Serialize a lock canonically — stable field order, sorted packs, newline. */
+export function serializeLock(lock: PragmaLock): string {
+  const packs = [...lock.packs]
+    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+    .map((pack) => ({
+      name: pack.name,
+      source: pack.source,
+      resolved: pack.resolved,
+      resolvedAt: pack.resolvedAt,
+    }));
+  return `${JSON.stringify(
+    { version: lock.version, contentHash: lock.contentHash, packs },
+    null,
+    2,
+  )}\n`;
+}
+
+/**
+ * Write the lock for a working directory.
+ *
+ * @param cwd - The project directory.
+ * @param lock - The lock to persist.
+ * @returns The exact bytes written (for the write effect / assertions).
+ * @note Impure — writes `pragma.lock.json`.
+ */
+export function writeLock(cwd: string, lock: PragmaLock): string {
+  const content = serializeLock(lock);
+  writeFileSync(lockPath(cwd), content);
+  return content;
+}

package/src/kernel/runtime/paths.ts

@@ -0,0 +1,37 @@
+/**
+ * Filesystem locations for the store layer: the content-addressed pack cache,
+ * the git-ref checkout cache, and the project lock file.
+ *
+ * The pack cache lives under `$XDG_CACHE_HOME/pragma/packs/<contentHash>/`
+ * (content-addressed, so a new source set is a new directory and invalidation
+ * is free); ref checkouts under `.../pragma/refs/`. The lock is a committed
+ * project artifact at `<cwd>/pragma.lock.json`. All cache paths derive from the
+ * config kernel's {@link cacheDir}, so the XDG isolation the tests install
+ * contains them.
+ */
+
+import { join } from "node:path";
+import { cacheDir } from "../config/paths.js";
+
+/** The lock file basename, committed at the project root. */
+export const LOCK_BASENAME = "pragma.lock.json";
+
+/** `$XDG_CACHE_HOME/pragma/packs` — the content-addressed pack cache root. */
+export function packsCacheDir(): string {
+  return join(cacheDir(), "packs");
+}
+
+/** `$XDG_CACHE_HOME/pragma/refs` — cached git-ref checkouts. */
+export function refsCacheDir(): string {
+  return join(cacheDir(), "refs");
+}
+
+/** The cache directory for a pack, named by its content hash. */
+export function packDir(contentHash: string): string {
+  return join(packsCacheDir(), contentHash);
+}
+
+/** The project lock file for a working directory. */
+export function lockPath(cwd: string): string {
+  return join(cwd, LOCK_BASENAME);
+}

package/src/kernel/runtime/probe.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { runStoreProbe } from "./probe.js";
+
+describe("store probe (in-process)", () => {
+  it("boots the embedded pack and reports entity + triple counts", async () => {
+    const out = JSON.parse(await runStoreProbe()) as {
+      ok: boolean;
+      entities: number;
+      triples: string;
+    };
+    expect(out.ok).toBe(true);
+    // The embedded sample pack ships six indexed entities (3 abox + 3 tbox).
+    expect(out.entities).toBe(6);
+    expect(Number(out.triples)).toBeGreaterThan(0);
+  });
+});

package/src/kernel/runtime/probe.ts

@@ -0,0 +1,39 @@
+/**
+ * The `__store-probe` diagnostic — boot the embedded pack and report a count.
+ *
+ * Its whole reason to exist is the compiled binary: it exercises the full
+ * store-boot path (oxigraph WASM load, n-quads cache load, `compileFromExtraction`,
+ * a SPARQL count) so a spawned-binary smoke test can prove the WASM and the
+ * embedded pack survive `bun build --compile`. A silent store-boot failure in
+ * the standalone binary is the one failure vitest's in-process suite cannot
+ * catch, so this is the guard. Storeless code never imports it — the bin
+ * fast-paths it behind a dynamic import.
+ */
+
+/**
+ * Boot the embedded pack and return a one-line JSON diagnostic.
+ *
+ * @returns `{ ok, entities, triples }` as compact JSON.
+ * @note Impure — materializes the embedded pack and boots a store.
+ */
+export async function runStoreProbe(): Promise<string> {
+  const [{ materializeEmbeddedPack }, { readPack }] = await Promise.all([
+    import("./graphpack/embedded.js"),
+    import("./graphpack/read.js"),
+  ]);
+  const session = await readPack(materializeEmbeddedPack());
+  try {
+    const result = await session.store.query(
+      "SELECT (COUNT(*) AS ?n) WHERE { ?s ?p ?o }" as never,
+    );
+    const triples =
+      result.type === "select" ? (result.bindings[0]?.n ?? "0") : "0";
+    return JSON.stringify({
+      ok: true,
+      entities: session.index.entities.length,
+      triples,
+    });
+  } finally {
+    session.store.dispose();
+  }
+}

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***@");
+}