@canonical/pragma-cli 0.27.1-experimental.0 → 0.30.0

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

@@ -0,0 +1,147 @@
+/**
+ * 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,
+  StoryFileEntry,
+} 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[];
+  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.
+ */
+export default function readPackageDir(dir: string): PackageDirContents {
+  return {
+    version: readVersion(dir),
+    graphs: readGraphs(dir),
+    skills: readSkills(dir),
+    stories: readStories(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 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 [];
+
+  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/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,120 @@
+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 });
+  });
+});
+
+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

@@ -6,16 +6,27 @@ import type { LookupResult } from "./contracts.js";
  *
  * 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[],
   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)),
   );
   const results: TResult[] = [];
+  let internalErrorCount = 0;
 
   for (const [index, outcome] of settled.entries()) {
     const query = queries[index];
@@ -35,11 +46,40 @@ export default async function lookupMany<TResult>(
         query,
         code: error.code,
         message: error.message,
+        ...(error.suggestions.length > 0 && {
+          suggestions: error.suggestions,
+        }),
       });
     } else {
-      throw error;
+      internalErrorCount += 1;
+      const reason = error instanceof Error ? error.message : String(error);
+      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" },
+    ]);
+  });
+});

package/src/domains/shared/mergeAndParseRefs.ts

@@ -0,0 +1,44 @@
+import {
+  type PackageRef,
+  parsePackageEntry,
+  type RawPackageEntry,
+} from "../refs/operations/parseRef.js";
+import readGlobalRefs from "../refs/operations/readGlobalRefs.js";
+import { DEFAULT_PACKAGES } from "./packages.js";
+
+/**
+ * Merge config packages, global refs, and the built-in defaults into a
+ * final parsed `PackageRef` array.
+ *
+ * Priority: config `packages` > global `refs.json` > hardcoded defaults.
+ * A non-empty config list is a full replacement — only the listed packages
+ * resolve. An empty or absent list means "not configured": global refs are
+ * merged over the defaults by package name, so a global entry for
+ * "@canonical/foo" overrides the default entry for the same package.
+ *
+ * Kept free of store imports so config-only consumers (e.g.
+ * `resolveConfiguredGraphs`) can merge refs without loading the ke/WASM
+ * runtime.
+ *
+ * @note Impure — reads global refs from `~/.config/pragma/refs.json`.
+ *
+ * @param configPackages - The `packages` field from `pragma.config.json`.
+ * @returns Parsed refs ready for the loader chain.
+ * @throws PragmaError with code CONFIG_ERROR when an entry is malformed.
+ */
+export function mergeAndParseRefs(
+  configPackages?: ReadonlyArray<RawPackageEntry>,
+): PackageRef[] {
+  // A non-empty config list replaces the package set entirely.
+  if (configPackages && configPackages.length > 0) {
+    return configPackages.map((entry) => parsePackageEntry(entry));
+  }
+
+  // Empty or absent → merge global refs over the defaults, keyed by name.
+  const merged = new Map<string, RawPackageEntry>();
+  for (const entry of [...DEFAULT_PACKAGES, ...readGlobalRefs()]) {
+    const name = typeof entry === "string" ? entry : entry.name;
+    merged.set(name, entry);
+  }
+  return [...merged.values()].map((entry) => parsePackageEntry(entry));
+}