@canonical/pragma-cli 0.29.0 → 0.31.0

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

@@ -28,16 +28,14 @@ export default function createLocalLoader(): PackageLoader {
       // 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 };
+        return { name: ref.pkg, source: "local", ...readPackageDir(ref.path) };
       }
 
       // 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 };
+      return { name: ref.pkg, source: "local", ...readPackageDir(dir) };
     },
   };
 }

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

@@ -0,0 +1,58 @@
+import { 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 readPackageDir from "./readPackageDir.js";
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "pragma-readpkg-"));
+});
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+/** Write a package.json into the temp package root. */
+function writeManifest(manifest: unknown): void {
+  writeFileSync(join(dir, "package.json"), JSON.stringify(manifest), "utf-8");
+}
+
+describe("readPackageDir — prefixes", () => {
+  it("reads package-declared prefixes from package.json pragma.prefixes", () => {
+    writeManifest({
+      version: "1.2.3",
+      pragma: { prefixes: { ds: "https://ds.canonical.com/" } },
+    });
+    const { version, prefixes } = readPackageDir(dir);
+    expect(version).toBe("1.2.3");
+    expect(prefixes).toEqual({ ds: "https://ds.canonical.com/" });
+  });
+
+  it("omits prefixes when the package declares none", () => {
+    writeManifest({ version: "1.0.0" });
+    expect(readPackageDir(dir).prefixes).toBeUndefined();
+  });
+
+  it("ignores a malformed pragma.prefixes field", () => {
+    writeManifest({ version: "1.0.0", pragma: { prefixes: "not-an-object" } });
+    expect(readPackageDir(dir).prefixes).toBeUndefined();
+  });
+
+  it("keeps only string-valued prefix entries", () => {
+    writeManifest({
+      version: "1.0.0",
+      pragma: { prefixes: { ds: "https://ds.canonical.com/", bad: 42 } },
+    });
+    expect(readPackageDir(dir).prefixes).toEqual({
+      ds: "https://ds.canonical.com/",
+    });
+  });
+
+  it("returns a default version and no prefixes when package.json is absent", () => {
+    const contents = readPackageDir(dir);
+    expect(contents.version).toBe("0.0.0");
+    expect(contents.prefixes).toBeUndefined();
+  });
+});

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

@@ -16,7 +16,11 @@ import {
   statSync,
 } from "node:fs";
 import { join } from "node:path";
-import type { GraphContent, SkillEntry } from "../semanticPackage.js";
+import type {
+  GraphContent,
+  SkillEntry,
+  StoryFileEntry,
+} from "../semanticPackage.js";
 
 // ---------------------------------------------------------------------------
 // TTL discovery convention
@@ -34,20 +38,26 @@ const TTL_DIRS: readonly { dir: string; glob: string }[] = [
 export interface PackageDirContents {
   readonly version: string;
   readonly graphs: GraphContent[];
+  readonly prefixes?: Readonly<Record<string, string>>;
   readonly skills: SkillEntry[];
+  readonly stories: StoryFileEntry[];
 }
 
 /**
  * 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.
+ * @returns Package version, TTL graph content, declared prefixes, and skills.
  */
 export default function readPackageDir(dir: string): PackageDirContents {
+  const manifest = readManifest(dir);
+  const prefixes = parsePrefixesField(manifest);
   return {
-    version: readVersion(dir),
+    version: typeof manifest.version === "string" ? manifest.version : "0.0.0",
     graphs: readGraphs(dir),
+    ...(prefixes ? { prefixes } : {}),
     skills: readSkills(dir),
+    stories: readStories(dir),
   };
 }
 
@@ -55,17 +65,51 @@ export default function readPackageDir(dir: string): PackageDirContents {
 // Helpers
 // ---------------------------------------------------------------------------
 
-function readVersion(dir: string): string {
-  const pjsonPath = join(dir, "package.json");
+/** A package.json shape with the fields this loader reads. */
+interface PackageManifest {
+  readonly version?: unknown;
+  readonly pragma?: unknown;
+}
+
+/** Read and parse `package.json`, returning an empty object on failure. */
+function readManifest(dir: string): PackageManifest {
   try {
-    const raw = readFileSync(pjsonPath, "utf-8");
-    const parsed = JSON.parse(raw) as { version?: string };
-    return parsed.version ?? "0.0.0";
+    return JSON.parse(
+      readFileSync(join(dir, "package.json"), "utf-8"),
+    ) as PackageManifest;
   } catch {
-    return "0.0.0";
+    return {};
   }
 }
 
+/**
+ * Extract package-declared prefixes from a parsed manifest.
+ *
+ * Convention: a package declares its namespaces under
+ * `pragma.prefixes` in `package.json`, e.g.
+ * `{ "pragma": { "prefixes": { "ds": "https://ds.canonical.com/" } } }`.
+ * Chosen over a separate file because the manifest is already read for the
+ * version, keeping the convention zero-extra-file and discoverable. Only
+ * string→string entries are kept; malformed shapes are ignored so one bad
+ * field cannot break boot.
+ *
+ * @returns The declared prefix map, or `undefined` when none is present.
+ */
+function parsePrefixesField(
+  manifest: PackageManifest,
+): Readonly<Record<string, string>> | undefined {
+  const pragma = manifest.pragma;
+  if (typeof pragma !== "object" || pragma === null) return undefined;
+  const raw = (pragma as { prefixes?: unknown }).prefixes;
+  if (typeof raw !== "object" || raw === null) return undefined;
+
+  const prefixes: Record<string, string> = {};
+  for (const [name, namespace] of Object.entries(raw)) {
+    if (typeof namespace === "string") prefixes[name] = namespace;
+  }
+  return Object.keys(prefixes).length > 0 ? prefixes : undefined;
+}
+
 function readGraphs(dir: string): GraphContent[] {
   const graphs: GraphContent[] = [];
 
@@ -87,6 +131,35 @@ function readGraphs(dir: string): GraphContent[] {
   return graphs;
 }
 
+function readStories(dir: string): StoryFileEntry[] {
+  const storiesDir = join(dir, "stories");
+  if (!existsSync(storiesDir)) return [];
+
+  const stories: StoryFileEntry[] = [];
+  try {
+    // Sorted: readdir order is filesystem-dependent, and story collision
+    // resolution must be deterministic across platforms.
+    for (const entry of [...readdirSync(storiesDir)].sort()) {
+      if (!entry.endsWith(".json")) continue;
+      const entryPath = join(storiesDir, entry);
+      try {
+        stories.push({
+          path: entryPath,
+          definition: JSON.parse(readFileSync(entryPath, "utf-8")),
+        });
+      } catch {
+        process.stderr.write(
+          `Warning: invalid JSON in story file ${entryPath}\n`,
+        );
+      }
+    }
+  } catch {
+    // readdir failed — no stories
+  }
+
+  return stories;
+}
+
 function readSkills(dir: string): SkillEntry[] {
   const skillsDir = join(dir, "skills");
   if (!existsSync(skillsDir)) return [];

package/src/domains/shared/loaders/storyAssetsPlugin.test.ts

@@ -0,0 +1,84 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { BunPlugin } from "bun";
+import { afterEach, describe, expect, it } from "vitest";
+import createStoryAssetsPlugin, {
+  STORY_ASSET_PATH_PATTERN,
+} from "./storyAssetsPlugin.js";
+
+interface OnLoadRegistration {
+  readonly filter: RegExp;
+  readonly callback: (args: { path: string }) => unknown;
+}
+
+/** Run the plugin's setup against a stub builder and capture its onLoad. */
+function captureOnLoadRegistration(): OnLoadRegistration {
+  let captured: OnLoadRegistration | undefined;
+  const builder = {
+    onLoad(
+      constraints: { filter: RegExp },
+      callback: OnLoadRegistration["callback"],
+    ): void {
+      captured = { filter: constraints.filter, callback };
+    },
+  };
+
+  createStoryAssetsPlugin().setup(
+    builder as unknown as Parameters<BunPlugin["setup"]>[0],
+  );
+
+  if (!captured) throw new Error("plugin did not register an onLoad handler");
+  return captured;
+}
+
+describe("STORY_ASSET_PATH_PATTERN", () => {
+  it("matches JSON directly inside a stories directory", () => {
+    expect(
+      STORY_ASSET_PATH_PATTERN.test(
+        "/repo/node_modules/@canonical/design-system/stories/color.json",
+      ),
+    ).toBe(true);
+  });
+
+  it("rejects manifests, nested files, near-miss directories, and non-JSON", () => {
+    const nonStories = [
+      "/repo/node_modules/@canonical/design-system/package.json",
+      "/repo/node_modules/@canonical/design-system/stories/nested/color.json",
+      "/repo/node_modules/@canonical/design-system/histories/color.json",
+      "/repo/node_modules/@canonical/design-system/stories/color.jsonc",
+      "/repo/node_modules/@canonical/design-system/stories/color.ttl",
+    ];
+    for (const path of nonStories) {
+      expect(STORY_ASSET_PATH_PATTERN.test(path), path).toBe(false);
+    }
+  });
+});
+
+describe("createStoryAssetsPlugin", () => {
+  let tmpDir: string | undefined;
+
+  afterEach(() => {
+    if (tmpDir) rmSync(tmpDir, { recursive: true, force: true });
+    tmpDir = undefined;
+  });
+
+  it("registers its load hook under the story path filter", () => {
+    const { filter } = captureOnLoadRegistration();
+    expect(filter).toBe(STORY_ASSET_PATH_PATTERN);
+  });
+
+  it("loads story JSON contents under the file loader", () => {
+    tmpDir = mkdtempSync(join(tmpdir(), "pragma-story-assets-"));
+    const storyPath = join(tmpDir, "color.json");
+    const content = JSON.stringify({ noun: "color" });
+    writeFileSync(storyPath, content);
+
+    const { callback } = captureOnLoadRegistration();
+
+    expect(callback({ path: storyPath })).toEqual({
+      contents: content,
+      loader: "file",
+    });
+  });
+});

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

@@ -0,0 +1,46 @@
+/**
+ * Build-time bundler plugin: embed story-pack JSON as file assets.
+ *
+ * Bun compiles `.json` build inputs into JSON modules, which never
+ * surface in `Bun.embeddedFiles`. Story-pack files must instead be
+ * embedded as file assets — like TTL graphs — so the bundled loader can
+ * serve them inside the compiled binary. This plugin scopes the `file`
+ * loader to story paths only, leaving every other JSON input (e.g.
+ * `package.json` imported for the CLI version) compiled as a module.
+ *
+ * Contract with the bundled loader: story files are the only `.json`
+ * content embedded as file assets, so every `.json` blob in
+ * `Bun.embeddedFiles` that is not named like a package manifest is a
+ * story definition. Consequence: no module in the bundle may import a
+ * `stories/*.json` file as a JSON module — the plugin would rewrite
+ * such an import into a file-path string.
+ *
+ * Consumed by `scripts/build.ts` only; never bundled into the binary.
+ */
+
+import { readFileSync } from "node:fs";
+import type { BunPlugin } from "bun";
+
+/**
+ * Matches story-pack files: a `.json` directly inside a `stories/`
+ * directory — the same non-recursive scope the local loader scans.
+ */
+export const STORY_ASSET_PATH_PATTERN = /[\\/]stories[\\/][^\\/]+\.json$/;
+
+/**
+ * Create the bundler plugin that embeds `stories/*.json` as file assets.
+ *
+ * @returns A `Bun.build` plugin for the compiled-binary build.
+ * @note Impure — the registered load callback reads the filesystem.
+ */
+export default function createStoryAssetsPlugin(): BunPlugin {
+  return {
+    name: "story-assets",
+    setup(build) {
+      build.onLoad({ filter: STORY_ASSET_PATH_PATTERN }, (args) => ({
+        contents: readFileSync(args.path, "utf-8"),
+        loader: "file",
+      }));
+    },
+  };
+}

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

@@ -0,0 +1,135 @@
+import { describe, expect, it } from "vitest";
+import { PragmaError } from "#error";
+import lookupMany, { lookupToolMeta } from "./lookupMany.js";
+
+describe("lookupMany", () => {
+  it("returns all results when every query resolves", async () => {
+    const result = await lookupMany(["a", "b"], async (q) => q.toUpperCase());
+
+    expect(result.results).toEqual(["A", "B"]);
+    expect(result.errors).toEqual([]);
+    expect(result.meta).toEqual({ internalErrorCount: 0 });
+  });
+
+  it("collects PragmaError failures as structured error entries", async () => {
+    const result = await lookupMany(["Button", "Buton"], async (q) => {
+      if (q === "Buton") {
+        throw PragmaError.notFound("block", q, { suggestions: ["Button"] });
+      }
+      return q;
+    });
+
+    expect(result.results).toEqual(["Button"]);
+    expect(result.errors).toEqual([
+      {
+        query: "Buton",
+        code: "ENTITY_NOT_FOUND",
+        message: 'block "Buton" not found.',
+        suggestions: ["Button"],
+      },
+    ]);
+    expect(result.meta).toEqual({ internalErrorCount: 0 });
+  });
+
+  it("keeps N-1 results when one query throws a non-PragmaError", async () => {
+    const result = await lookupMany(
+      ["a", "poisoned", "c"],
+      async (q): Promise<string> => {
+        if (q === "poisoned") {
+          throw new TypeError("cannot read properties of undefined");
+        }
+        return q.toUpperCase();
+      },
+    );
+
+    expect(result.results).toEqual(["A", "C"]);
+    expect(result.errors).toEqual([
+      {
+        query: "poisoned",
+        code: "INTERNAL_ERROR",
+        message: "Internal error: cannot read properties of undefined",
+      },
+    ]);
+    expect(result.meta).toEqual({ internalErrorCount: 1 });
+  });
+
+  it("stringifies non-Error rejection values", async () => {
+    const result = await lookupMany(["a"], async () => {
+      throw "string failure";
+    });
+
+    expect(result.results).toEqual([]);
+    expect(result.errors).toEqual([
+      {
+        query: "a",
+        code: "INTERNAL_ERROR",
+        message: "Internal error: string failure",
+      },
+    ]);
+    expect(result.meta).toEqual({ internalErrorCount: 1 });
+  });
+
+  it("counts each internal error and mixes with PragmaError entries", async () => {
+    const result = await lookupMany(
+      ["ok", "missing", "boom-1", "boom-2"],
+      async (q): Promise<string> => {
+        if (q === "missing") throw PragmaError.notFound("token", q);
+        if (q.startsWith("boom")) throw new Error(q);
+        return q;
+      },
+    );
+
+    expect(result.results).toEqual(["ok"]);
+    expect(result.errors).toHaveLength(3);
+    expect(result.errors.map((e) => e.code)).toEqual([
+      "ENTITY_NOT_FOUND",
+      "INTERNAL_ERROR",
+      "INTERNAL_ERROR",
+    ]);
+    expect(result.meta).toEqual({ internalErrorCount: 2 });
+  });
+
+  it("reclassifies a rejected SPARQL value as INVALID_INPUT, not internal", async () => {
+    const result = await lookupMany(["}; DROP"], async (q) => {
+      throw new Error(
+        `Potentially dangerous SPARQL value rejected: ${JSON.stringify(q)}`,
+      );
+    });
+
+    expect(result.results).toEqual([]);
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors.at(0)?.code).toBe("INVALID_INPUT");
+    expect(result.errors.at(0)?.message).not.toContain("Internal error");
+    // A rejected value is user input, so it is not counted as an internal fault.
+    expect(result.meta).toEqual({ internalErrorCount: 0 });
+  });
+});
+
+describe("lookupToolMeta", () => {
+  it("reports count and omits internalErrorCount when zero", async () => {
+    const result = await lookupMany(["a", "b"], async (q) => q);
+
+    expect(lookupToolMeta(result)).toEqual({ count: 2 });
+  });
+
+  it("includes internalErrorCount when at least one query failed unexpectedly", async () => {
+    const result = await lookupMany(
+      ["a", "boom"],
+      async (q): Promise<string> => {
+        if (q === "boom") throw new Error("boom");
+        return q;
+      },
+    );
+
+    expect(lookupToolMeta(result)).toEqual({
+      count: 1,
+      internalErrorCount: 1,
+    });
+  });
+
+  it("tolerates hand-built results without meta", () => {
+    expect(lookupToolMeta({ results: ["x"], errors: [] })).toEqual({
+      count: 1,
+    });
+  });
+});

package/src/domains/shared/lookupMany.ts

@@ -1,11 +1,23 @@
 import { PragmaError } from "#error";
 import type { LookupResult } from "./contracts.js";
 
+/**
+ * Marker in the ke SPARQL guard's rejection message. A rejected value is user
+ * input, not an internal fault, so it is reclassified as INVALID_INPUT rather
+ * than mislabelled as an internal error.
+ */
+const SPARQL_REJECTION_MARKER = "Potentially dangerous SPARQL value rejected";
+
 /**
  * Resolve multiple lookup queries and collect structured per-query failures.
  *
  * Used by MCP lookup tools so a single call can return multiple results
  * without failing the entire request when one query is missing.
+ *
+ * The collection loop never rejects: a `PragmaError` becomes an error entry
+ * with its own code, and any other thrown value becomes an `INTERNAL_ERROR`
+ * entry — so one poisoned query cannot discard the other queries' results.
+ * `meta.internalErrorCount` reports how many entries are internal errors.
  */
 export default async function lookupMany<TResult>(
   queries: readonly string[],
@@ -21,6 +33,7 @@ export default async function lookupMany<TResult>(
     queries.map((query) => lookup(query)),
   );
   const results: TResult[] = [];
+  let internalErrorCount = 0;
 
   for (const [index, outcome] of settled.entries()) {
     const query = queries[index];
@@ -45,9 +58,44 @@ export default async function lookupMany<TResult>(
         }),
       });
     } else {
-      throw error;
+      const reason = error instanceof Error ? error.message : String(error);
+      if (reason.includes(SPARQL_REJECTION_MARKER)) {
+        // A rejected value is invalid user input, not an internal fault.
+        errors.push({
+          query,
+          code: "INVALID_INPUT",
+          message: `Invalid lookup value "${query}": rejected as unsafe.`,
+        });
+      } else {
+        internalErrorCount += 1;
+        errors.push({
+          query,
+          code: "INTERNAL_ERROR",
+          message: `Internal error: ${reason}`,
+        });
+      }
     }
   }
 
-  return { results, errors };
+  return { results, errors, meta: { internalErrorCount } };
+}
+
+/**
+ * Build MCP envelope metadata for a lookup result.
+ *
+ * Always reports `count`; includes `internalErrorCount` only when at least
+ * one query failed unexpectedly, so healthy responses stay unchanged.
+ *
+ * @param result - A lookup result, typically produced via {@link lookupMany}.
+ * @returns Meta object for the `{ ok, data, meta }` tool envelope.
+ */
+export function lookupToolMeta<TResult>(result: LookupResult<TResult>): {
+  count: number;
+  internalErrorCount?: number;
+} {
+  const internalErrorCount = result.meta?.internalErrorCount ?? 0;
+  return {
+    count: result.results.length,
+    ...(internalErrorCount > 0 && { internalErrorCount }),
+  };
 }

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

@@ -0,0 +1,89 @@
+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 type { RawPackageEntry } from "../refs/operations/parseRef.js";
+import { mergeAndParseRefs } from "./mergeAndParseRefs.js";
+import { DEFAULT_PACKAGES } from "./packages.js";
+
+const DEFAULT_NAMES = DEFAULT_PACKAGES.map((entry) =>
+  typeof entry === "string" ? entry : entry.name,
+);
+
+function writeGlobalRefs(
+  xdgDir: string,
+  packages: ReadonlyArray<RawPackageEntry>,
+): void {
+  const dir = join(xdgDir, "pragma");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "refs.json"), JSON.stringify({ packages }));
+}
+
+describe("mergeAndParseRefs", () => {
+  let tmpDir: string;
+  const origEnv = { ...process.env };
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "pragma-merge-refs-"));
+    // Point XDG_CONFIG_HOME to our temp dir so readGlobalRefs() resolves there
+    process.env.XDG_CONFIG_HOME = tmpDir;
+  });
+
+  afterEach(() => {
+    process.env = { ...origEnv };
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("returns parsed defaults when config and global refs are absent", () => {
+    const refs = mergeAndParseRefs(undefined);
+    expect(refs.map((ref) => ref.pkg)).toEqual(DEFAULT_NAMES);
+    expect(refs.every((ref) => ref.kind === "git")).toBe(true);
+  });
+
+  it("treats an explicitly empty config list as not configured", () => {
+    expect(mergeAndParseRefs([])).toEqual(mergeAndParseRefs(undefined));
+  });
+
+  it("falls back to global refs when the config list is empty", () => {
+    writeGlobalRefs(tmpDir, [
+      { name: "@canonical/design-system", source: "file:///tmp/ds" },
+    ]);
+
+    const refs = mergeAndParseRefs([]);
+
+    expect(refs.map((ref) => ref.pkg)).toEqual(DEFAULT_NAMES);
+    expect(refs.at(0)).toEqual({
+      kind: "file",
+      pkg: "@canonical/design-system",
+      path: "/tmp/ds",
+    });
+  });
+
+  it("merges global refs over defaults by package name", () => {
+    writeGlobalRefs(tmpDir, [
+      { name: "@canonical/design-system", source: "file:///tmp/ds" },
+      "@acme/extra",
+    ]);
+
+    const refs = mergeAndParseRefs(undefined);
+
+    expect(refs.map((ref) => ref.pkg)).toEqual([
+      ...DEFAULT_NAMES,
+      "@acme/extra",
+    ]);
+    expect(refs.at(0)?.kind).toBe("file");
+    expect(refs.at(-1)).toEqual({ kind: "npm", pkg: "@acme/extra" });
+  });
+
+  it("replaces defaults and global refs with a non-empty config list", () => {
+    writeGlobalRefs(tmpDir, ["@acme/global-only"]);
+
+    const refs = mergeAndParseRefs([
+      { name: "@acme/only", source: "file:///tmp/only" },
+    ]);
+
+    expect(refs).toEqual([
+      { kind: "file", pkg: "@acme/only", path: "/tmp/only" },
+    ]);
+  });
+});