@canonical/pragma-cli 0.27.0 → 0.29.0

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

@@ -157,8 +157,11 @@ describe("updateRefs", () => {
 
   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);
+    // 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);
+    }
   });
 });

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

@@ -152,8 +152,9 @@ function mergeEntries(
 
   const merged = new Map<string, RawPackageEntry>();
 
-  for (const pkg of DEFAULT_PACKAGES) {
-    merged.set(pkg, pkg);
+  for (const entry of DEFAULT_PACKAGES) {
+    const name = typeof entry === "string" ? entry : entry.name;
+    merged.set(name, entry);
   }
   for (const entry of globalEntries) {
     const name = typeof entry === "string" ? entry : entry.name;

package/src/domains/shared/bootStore.ts

@@ -1,85 +1,124 @@
 /**
- * Boot a ke store from pragma.config.json sources.
+ * Boot a ke store from resolved semantic packages.
  *
- * Reads configuration, resolves sources (defaults or overridden),
- * creates the store with registered prefixes, and wraps errors.
+ * Resolves packages via the loader chain (local > git > bundled),
+ * then loads all graph content into the store.
  *
  * @note Impure — reads filesystem, creates ke store.
  */
 
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-import type { SourceSpec, Store } from "@canonical/ke";
-import { createStore } from "@canonical/ke";
+import {
+  createStore,
+  definePlugin,
+  type Plugin,
+  type SourceSpec,
+  type Store,
+} from "@canonical/ke";
 import { PragmaError } from "../../error/index.js";
 import type { PackageRef } from "../refs/operations/parseRef.js";
-import { resolvePackages } from "./packages.js";
+import { parsePackageEntry } from "../refs/operations/parseRef.js";
+import {
+  createBundledLoader,
+  createGitLoader,
+  createLocalLoader,
+} from "./loaders/index.js";
+import { DEFAULT_PACKAGES } from "./packages.js";
 import { PREFIX_MAP } from "./prefixes.js";
-
-/**
- * Convention-based TTL directories to scan in each package.
- * Only directories that exist are globbed — packages that lack
- * a `data/` or `definitions/` dir are silently skipped.
- */
-const TTL_DIRS: readonly { dir: string; glob: string }[] = [
-  { dir: "definitions", glob: "definitions/**/*.ttl" },
-  { dir: "data", glob: "data/**/*.ttl" },
-];
-
-/**
- * Resolve default TTL sources from resolved packages.
- *
- * Uses convention-based TTL discovery: definitions and data globs
- * relative to each package root. Only adds globs for directories
- * that actually exist in the package.
- *
- * @param refs - Parsed package references. Omit for defaults.
- */
-export function defaultSources(refs?: ReadonlyArray<PackageRef>): SourceSpec[] {
-  const sources: SourceSpec[] = [];
-  const resolved = resolvePackages(refs);
-
-  for (const { dir } of resolved) {
-    for (const entry of TTL_DIRS) {
-      if (existsSync(join(dir, entry.dir))) {
-        sources.push(join(dir, entry.glob));
-      }
-    }
-  }
-
-  return sources;
-}
+import type { GraphContent, SemanticPackage } from "./semanticPackage.js";
+import { resolveSemanticPackages } from "./semanticPackage.js";
 
 export interface BootStoreOptions {
-  /** Override sources (skip filesystem resolution). */
+  /** Override sources (skip package resolution — for testing). */
   sources?: SourceSpec[];
   /** Working directory for resolving relative paths. */
   cwd?: string;
   /** Cache path for serialized store. */
   cache?: string;
-  /** Parsed package references for ref-based resolution. */
+  /** Parsed package references for loader-based resolution. */
   refs?: ReadonlyArray<PackageRef>;
+  /** Enable query tracing (from config). Env var PRAGMA_TRACE=1 overrides. */
+  trace?: boolean;
+}
+
+export interface BootResult {
+  /** The initialized ke store. */
+  readonly store: Store;
+  /** Resolved semantic packages (empty when sources override is used). */
+  readonly packages: readonly SemanticPackage[];
 }
 
 /**
  * Boot a ke store from configuration.
  *
+ * When `sources` is provided, uses them directly (testing path).
+ * Otherwise, resolves packages via the loader chain and loads their
+ * graph content into the store.
+ *
  * @throws PragmaError with code STORE_ERROR on failure.
  */
 export async function bootStore(
   options: BootStoreOptions = {},
-): Promise<Store> {
-  const sources = options.sources ?? defaultSources(options.refs);
-
+): Promise<BootResult> {
   try {
+    // Testing/programmatic override — use explicit sources
+    if (options.sources) {
+      const store = await createStore({
+        sources: options.sources,
+        prefixes: PREFIX_MAP,
+        cache: options.cache,
+        cwd: options.cwd,
+      });
+      return { store, packages: [] };
+    }
+
+    // Resolve packages via loader chain: local > git > bundled
+    const refs =
+      options.refs && options.refs.length > 0
+        ? options.refs
+        : DEFAULT_PACKAGES.map(parsePackageEntry);
+    // Precedence: local (file:// + node_modules) > git cache > bundled
+    const loaders = [
+      createLocalLoader(),
+      createGitLoader(),
+      createBundledLoader(),
+    ];
+    const packages = await resolveSemanticPackages(refs, loaders);
+
+    // Collect all graph content from resolved packages
+    const allGraphs = packages.flatMap((pkg) => pkg.graphs);
+
+    // Use a ke plugin to load graph content during store creation.
+    // The onReady hook has access to ctx.load() which loads raw content.
+    const graphLoaderPlugin = definePlugin({
+      name: "pragma-graph-loader",
+      onReady(ctx) {
+        for (const graph of allGraphs) {
+          ctx.load(graph.content, { format: graph.format });
+        }
+      },
+    });
+
+    // biome-ignore lint: Plugin generic variance requires explicit unknown
+    const plugins: Plugin<any>[] = [graphLoaderPlugin];
+    const traceEnabled =
+      process.env.PRAGMA_TRACE === "1" || options.trace === true;
+    if (traceEnabled) {
+      const { createTracePlugin } = await import("../trace/tracePlugin.js");
+      const { traceDir } = await import("../refs/operations/paths.js");
+      plugins.push(createTracePlugin({ traceDir: traceDir() }));
+    }
+
     const store = await createStore({
-      sources,
+      sources: [],
       prefixes: PREFIX_MAP,
       cache: options.cache,
       cwd: options.cwd,
+      plugins,
     });
-    return store;
+
+    return { store, packages };
   } catch (error) {
+    if (error instanceof PragmaError) throw error;
     throw PragmaError.storeError(
       error instanceof Error ? error.message : String(error),
       {

package/src/domains/shared/contracts.ts

@@ -56,6 +56,7 @@ export interface LookupResult<T> {
     query: string;
     code: string;
     message: string;
+    suggestions?: readonly string[];
   }[];
 }
 

package/src/domains/shared/emptyErrorRecovery.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from "vitest";
+import type { PragmaError } from "#error";
+import blockSpecs from "../block/mcp/specs.js";
+import blockEmptyError from "../block/orchestration/blockEmptyError.js";
+import modifierSpecs from "../modifier/mcp/specs.js";
+import modifierEmptyError from "../modifier/orchestration/modifierEmptyError.js";
+import standardSpecs from "../standard/mcp/specs.js";
+import standardEmptyError from "../standard/orchestration/standardEmptyError.js";
+import tokenSpecs from "../token/mcp/specs.js";
+import tokenEmptyError from "../token/orchestration/tokenEmptyError.js";
+import type { FilterConfig } from "./types/index.js";
+
+const filters: FilterConfig = { tier: "Apps/WPE", channel: "normal" };
+const allTiers: FilterConfig = { tier: undefined, channel: "normal" };
+
+/**
+ * Every distinct empty-result scenario each domain can produce, paired with the
+ * set of MCP tool names that domain actually registers. The invariant below
+ * holds the four hints to the S-grade contract so authored consistency cannot
+ * silently re-drift.
+ */
+const cases: ReadonlyArray<{
+  domain: string;
+  error: PragmaError;
+  toolNames: ReadonlySet<string>;
+  // store-empty (packages absent) → the install rung, which must NOT carry an
+  // mcp retry (re-listing an absent store loops). filter-narrowing → may carry
+  // a list-retry mcp pointer.
+  storeEmpty: boolean;
+}> = [
+  {
+    domain: "block (filter active)",
+    error: blockEmptyError(filters, false),
+    toolNames: new Set(blockSpecs.map((s) => s.name)),
+    storeEmpty: false,
+  },
+  {
+    domain: "block (all tiers — terminal)",
+    error: blockEmptyError(allTiers, true),
+    toolNames: new Set(blockSpecs.map((s) => s.name)),
+    storeEmpty: false,
+  },
+  {
+    domain: "token (category active)",
+    error: tokenEmptyError("color"),
+    toolNames: new Set(tokenSpecs.map((s) => s.name)),
+    storeEmpty: false,
+  },
+  {
+    domain: "token (store-empty)",
+    error: tokenEmptyError(),
+    toolNames: new Set(tokenSpecs.map((s) => s.name)),
+    storeEmpty: true,
+  },
+  {
+    domain: "modifier (store-empty)",
+    error: modifierEmptyError(),
+    toolNames: new Set(modifierSpecs.map((s) => s.name)),
+    storeEmpty: true,
+  },
+  {
+    domain: "standard (filter active)",
+    error: standardEmptyError({ category: "react" }),
+    toolNames: new Set(standardSpecs.map((s) => s.name)),
+    storeEmpty: false,
+  },
+  {
+    domain: "standard (store-empty)",
+    error: standardEmptyError({}),
+    toolNames: new Set(standardSpecs.map((s) => s.name)),
+    storeEmpty: true,
+  },
+];
+
+describe("empty-error recovery contract (cross-domain)", () => {
+  it.each(cases)("$domain honours the S-grade recovery shape", ({
+    error,
+    toolNames,
+    storeEmpty,
+  }) => {
+    const recovery = error.recovery;
+
+    // Terminal state (e.g. block already at all-tiers) is allowed.
+    if (recovery === undefined) return;
+
+    // Every hint carries a human-readable message.
+    expect(recovery.message).toBeTruthy();
+
+    // No hint is message-only: a runnable cli is always present (either a
+    // pragma re-list for filter-narrowing, or a bun add for store-empty).
+    expect(recovery.cli).toBeTruthy();
+
+    if (storeEmpty) {
+      // Store-empty must NOT carry an mcp retry: re-listing an absent store
+      // just loops. This is the anti-drift guard for the install rung.
+      expect(recovery.mcp).toBeUndefined();
+    } else if (recovery.mcp !== undefined) {
+      // A filter-narrowing mcp pointer must name a tool the domain actually
+      // registers — catches renamed/dangling tool references.
+      expect(toolNames.has(recovery.mcp.tool)).toBe(true);
+    }
+  });
+
+  it("never points an install hint at @canonical/ds-global (not a real default)", () => {
+    for (const { error } of cases) {
+      expect(error.recovery?.cli ?? "").not.toContain("ds-global");
+    }
+  });
+});

package/src/domains/shared/loaders/bundledLoader.ts

@@ -0,0 +1,108 @@
+/**
+ * Bundled package loader for compiled binaries.
+ *
+ * Resolves semantic content from `Bun.embeddedFiles` — TTL and skill
+ * files embedded into the compiled binary via the build command.
+ *
+ * Blob names are hashed by bun (e.g. `button-a1b2c3d4.ttl`), losing
+ * directory and package association. The loader therefore returns a
+ * single SemanticPackage containing ALL embedded TTL content. RDF
+ * stores deduplicate triples, so this is safe when combined with
+ * higher-precedence loaders that resolve individual packages.
+ *
+ * @note Impure — reads embedded blobs.
+ */
+
+import type { PackageRef } from "../../refs/operations/parseRef.js";
+import type {
+  GraphContent,
+  PackageLoader,
+  SemanticPackage,
+} from "../semanticPackage.js";
+
+// ---------------------------------------------------------------------------
+// State
+// ---------------------------------------------------------------------------
+
+/** Cached result — embedded content is immutable, no need to re-read. */
+let cached: SemanticPackage | undefined;
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export default function createBundledLoader(): PackageLoader {
+  return {
+    name: "bundled",
+    async resolve(_ref: PackageRef): Promise<SemanticPackage | undefined> {
+      if (cached) return cached;
+
+      if (typeof globalThis.Bun === "undefined") return undefined;
+      // Bun.embeddedFiles blobs have a .name property at runtime
+      const blobs = (globalThis.Bun as { embeddedFiles?: readonly Blob[] })
+        .embeddedFiles as ReadonlyArray<Blob & { name: string }> | undefined;
+      if (!blobs?.length) return undefined;
+
+      const graphs = await readEmbeddedGraphs(blobs);
+      if (graphs.length === 0) return undefined;
+
+      const version = await readEmbeddedVersion(blobs);
+
+      cached = {
+        name: "(bundled)",
+        version,
+        source: "bundled",
+        graphs,
+        skills: [],
+      };
+
+      return cached;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Graph reading
+// ---------------------------------------------------------------------------
+
+async function readEmbeddedGraphs(
+  blobs: ReadonlyArray<Blob & { name: string }>,
+): Promise<GraphContent[]> {
+  const graphs: GraphContent[] = [];
+
+  for (const blob of blobs) {
+    if (!blob.name.endsWith(".ttl")) continue;
+
+    try {
+      const content = await blob.text();
+      graphs.push({
+        path: `(bundled)/${blob.name}`,
+        content,
+        format: "turtle",
+      });
+    } catch {}
+  }
+
+  return graphs;
+}
+
+// ---------------------------------------------------------------------------
+// Version reading
+// ---------------------------------------------------------------------------
+
+async function readEmbeddedVersion(
+  blobs: ReadonlyArray<Blob & { name: string }>,
+): Promise<string> {
+  for (const blob of blobs) {
+    if (!blob.name.includes("package") || !blob.name.endsWith(".json"))
+      continue;
+
+    try {
+      const text = await blob.text();
+      const parsed = JSON.parse(text) as { version?: string };
+      if (parsed.version) return parsed.version;
+    } catch {}
+  }
+
+  return "0.0.0";
+}

package/src/domains/shared/loaders/gitLoader.ts

@@ -0,0 +1,31 @@
+/**
+ * Git cache package loader.
+ *
+ * Resolves semantic packages from the git ref cache at
+ * `~/.cache/pragma/refs/<pkg>/<ref>/`, populated by `pragma update-refs`.
+ *
+ * Only handles `git` kind refs. File and npm refs are skipped.
+ *
+ * @note Impure — reads filesystem.
+ */
+
+import { existsSync } from "node:fs";
+import type { PackageRef } from "../../refs/operations/parseRef.js";
+import { gitCacheDir } from "../../refs/operations/paths.js";
+import type { PackageLoader, SemanticPackage } from "../semanticPackage.js";
+import readPackageDir from "./readPackageDir.js";
+
+export default function createGitLoader(): PackageLoader {
+  return {
+    name: "git",
+    resolve(ref: PackageRef): SemanticPackage | undefined {
+      if (ref.kind !== "git") return undefined;
+
+      const dir = gitCacheDir(ref.pkg, ref.ref);
+      if (!existsSync(dir)) return undefined;
+
+      const { version, graphs, skills } = readPackageDir(dir);
+      return { name: ref.pkg, version, source: "git", graphs, skills };
+    },
+  };
+}

package/src/domains/shared/loaders/index.ts

@@ -0,0 +1,6 @@
+/** @module Semantic package loaders — local, git, and bundled resolution. */
+
+export { default as createBundledLoader } from "./bundledLoader.js";
+export { default as createGitLoader } from "./gitLoader.js";
+export { default as createLocalLoader } from "./localLoader.js";
+export { default as readPackageDir } from "./readPackageDir.js";

package/src/domains/shared/loaders/localLoader.ts

@@ -0,0 +1,73 @@
+/**
+ * Local package loader.
+ *
+ * Resolves semantic packages from the local filesystem:
+ * - `file://` refs → direct path check
+ * - All ref kinds → upward `node_modules` walk from this module's location
+ *
+ * The node_modules walk avoids `require.resolve('pkg/package.json')` which
+ * breaks for packages with strict `exports` fields (e.g. @canonical/anatomy-dsl).
+ *
+ * @note Impure — reads filesystem.
+ */
+
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { PackageRef } from "../../refs/operations/parseRef.js";
+import type { PackageLoader, SemanticPackage } from "../semanticPackage.js";
+import readPackageDir from "./readPackageDir.js";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export default function createLocalLoader(): PackageLoader {
+  return {
+    name: "local",
+    resolve(ref: PackageRef): SemanticPackage | undefined {
+      // file:// refs → direct path check first
+      if (ref.kind === "file") {
+        if (!existsSync(ref.path)) return undefined;
+        const { version, graphs, skills } = readPackageDir(ref.path);
+        return { name: ref.pkg, version, source: "local", graphs, skills };
+      }
+
+      // All ref kinds → try node_modules walk
+      const dir = findPackageDir(ref.pkg);
+      if (!dir) return undefined;
+
+      const { version, graphs, skills } = readPackageDir(dir);
+      return { name: ref.pkg, version, source: "local", graphs, skills };
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// node_modules walk
+// ---------------------------------------------------------------------------
+
+/**
+ * Find a package directory by walking up from this module's location.
+ *
+ * Checks each ancestor's `node_modules/<pkg>` directory. Handles both
+ * scoped (`@scope/name`) and unscoped packages. Follows symlinks via
+ * `realpathSync` so hoisted workspace layouts resolve correctly.
+ */
+function findPackageDir(pkg: string): string | undefined {
+  const segments = pkg.split("/");
+  let current = import.meta.dirname;
+
+  while (current !== dirname(current)) {
+    const candidate = join(current, "node_modules", ...segments);
+    if (existsSync(candidate)) {
+      try {
+        return realpathSync(candidate);
+      } catch {
+        return candidate;
+      }
+    }
+    current = dirname(current);
+  }
+
+  return undefined;
+}

package/src/domains/shared/loaders/readPackageDir.ts

@@ -0,0 +1,112 @@
+/**
+ * Read semantic content from a package directory on disk.
+ *
+ * Shared by LocalLoader and GitLoader. Given a directory path, reads
+ * package.json for version, globs TTL files from definitions/ and data/,
+ * and scans skills/ for subdirectories.
+ *
+ * @note Impure — reads filesystem.
+ */
+
+import {
+  existsSync,
+  globSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+} from "node:fs";
+import { join } from "node:path";
+import type { GraphContent, SkillEntry } from "../semanticPackage.js";
+
+// ---------------------------------------------------------------------------
+// TTL discovery convention
+// ---------------------------------------------------------------------------
+
+const TTL_DIRS: readonly { dir: string; glob: string }[] = [
+  { dir: "definitions", glob: "definitions/**/*.ttl" },
+  { dir: "data", glob: "data/**/*.ttl" },
+];
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface PackageDirContents {
+  readonly version: string;
+  readonly graphs: GraphContent[];
+  readonly skills: SkillEntry[];
+}
+
+/**
+ * Read semantic package content from a directory.
+ *
+ * @param dir - Absolute path to the package root directory.
+ * @returns Package version, TTL graph content, and skill entries.
+ */
+export default function readPackageDir(dir: string): PackageDirContents {
+  return {
+    version: readVersion(dir),
+    graphs: readGraphs(dir),
+    skills: readSkills(dir),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function readVersion(dir: string): string {
+  const pjsonPath = join(dir, "package.json");
+  try {
+    const raw = readFileSync(pjsonPath, "utf-8");
+    const parsed = JSON.parse(raw) as { version?: string };
+    return parsed.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+function readGraphs(dir: string): GraphContent[] {
+  const graphs: GraphContent[] = [];
+
+  for (const entry of TTL_DIRS) {
+    if (!existsSync(join(dir, entry.dir))) continue;
+
+    const files = globSync(entry.glob, { cwd: dir });
+    for (const file of files) {
+      const absPath = join(dir, file);
+      try {
+        const content = readFileSync(absPath, "utf-8");
+        graphs.push({ path: absPath, content, format: "turtle" });
+      } catch {
+        // Unreadable file — skip silently
+      }
+    }
+  }
+
+  return graphs;
+}
+
+function readSkills(dir: string): SkillEntry[] {
+  const skillsDir = join(dir, "skills");
+  if (!existsSync(skillsDir)) return [];
+
+  const skills: SkillEntry[] = [];
+  try {
+    const entries = readdirSync(skillsDir);
+    for (const entry of entries) {
+      const entryPath = join(skillsDir, entry);
+      try {
+        if (statSync(entryPath).isDirectory()) {
+          skills.push({ dir: entryPath, folderName: entry });
+        }
+      } catch {
+        // stat failed — skip
+      }
+    }
+  } catch {
+    // readdir failed — no skills
+  }
+
+  return skills;
+}

package/src/domains/shared/lookupMany.ts

@@ -11,7 +11,12 @@ export default async function lookupMany<TResult>(
   queries: readonly string[],
   lookup: (query: string) => Promise<TResult>,
 ): Promise<LookupResult<TResult>> {
-  const errors: Array<{ query: string; code: string; message: string }> = [];
+  const errors: Array<{
+    query: string;
+    code: string;
+    message: string;
+    suggestions?: readonly string[];
+  }> = [];
   const settled = await Promise.allSettled(
     queries.map((query) => lookup(query)),
   );
@@ -35,6 +40,9 @@ export default async function lookupMany<TResult>(
         query,
         code: error.code,
         message: error.message,
+        ...(error.suggestions.length > 0 && {
+          suggestions: error.suggestions,
+        }),
       });
     } else {
       throw error;