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

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.test.ts

@@ -0,0 +1,248 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { PackageRef } from "../../refs/operations/parseRef.js";
+import createBundledLoader, {
+  resetBundledLoaderCache,
+} from "./bundledLoader.js";
+
+const ref: PackageRef = { kind: "npm", pkg: "@canonical/design-system" };
+
+/** Minimal stand-in for a Bun embedded-file blob. */
+interface FakeBlob {
+  readonly name: string;
+  text(): Promise<string>;
+}
+
+const blob = (name: string, content: string): FakeBlob => ({
+  name,
+  text: async () => content,
+});
+
+const corruptBlob = (name: string): FakeBlob => ({
+  name,
+  text: async () => {
+    throw new Error("embedded blob unreadable");
+  },
+});
+
+const TTL = "@prefix ds: <https://example.test/ds#> .";
+
+function stubEmbeddedFiles(blobs: readonly FakeBlob[]): void {
+  (globalThis as { Bun?: unknown }).Bun = { embeddedFiles: blobs };
+}
+
+const hadBun = typeof (globalThis as { Bun?: unknown }).Bun !== "undefined";
+const originalBun = (globalThis as { Bun?: unknown }).Bun;
+
+let stderrSpy: ReturnType<typeof vi.spyOn>;
+
+beforeEach(() => {
+  resetBundledLoaderCache();
+  stderrSpy = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+});
+
+afterEach(() => {
+  resetBundledLoaderCache();
+  if (hadBun) {
+    (globalThis as { Bun?: unknown }).Bun = originalBun;
+  } else {
+    delete (globalThis as { Bun?: unknown }).Bun;
+  }
+  stderrSpy.mockRestore();
+});
+
+const stderrText = (): string =>
+  stderrSpy.mock.calls.map((call) => String(call[0])).join("");
+
+describe("createBundledLoader", () => {
+  it("returns undefined outside a compiled Bun binary", async () => {
+    if (!hadBun) {
+      delete (globalThis as { Bun?: unknown }).Bun;
+      const resolved = await createBundledLoader().resolve(ref);
+      expect(resolved).toBeUndefined();
+    }
+  });
+
+  it("bundles all embedded TTL and reads the manifest version", async () => {
+    stubEmbeddedFiles([
+      blob("button-a1b2c3d4.ttl", TTL),
+      blob("package-a1b2c3d4.json", JSON.stringify({ version: "1.2.3" })),
+    ]);
+
+    const resolved = await createBundledLoader().resolve(ref);
+
+    expect(resolved).toBeDefined();
+    expect(resolved?.source).toBe("bundled");
+    expect(resolved?.version).toBe("1.2.3");
+    expect(resolved?.graphs).toEqual([
+      {
+        path: "(bundled)/button-a1b2c3d4.ttl",
+        content: TTL,
+        format: "turtle",
+      },
+    ]);
+  });
+
+  it("accepts a plain package.json basename", async () => {
+    stubEmbeddedFiles([
+      blob("button.ttl", TTL),
+      blob("package.json", JSON.stringify({ version: "2.0.0" })),
+    ]);
+
+    const resolved = await createBundledLoader().resolve(ref);
+    expect(resolved?.version).toBe("2.0.0");
+  });
+
+  it("warns and skips a corrupt TTL blob instead of silently dropping it", async () => {
+    stubEmbeddedFiles([
+      blob("good-a1b2c3d4.ttl", TTL),
+      corruptBlob("bad-a1b2c3d4.ttl"),
+    ]);
+
+    const resolved = await createBundledLoader().resolve(ref);
+
+    expect(resolved?.graphs).toHaveLength(1);
+    expect(stderrText()).toContain("bad-a1b2c3d4.ttl");
+    expect(stderrText()).toContain("embedded blob unreadable");
+  });
+
+  it("serves embedded story JSON as story-file entries", async () => {
+    stubEmbeddedFiles([
+      blob("button-a1b2c3d4.ttl", TTL),
+      blob("package-a1b2c3d4.json", JSON.stringify({ version: "1.2.3" })),
+      blob("colors-fyskc7pf.json", JSON.stringify({ noun: "color" })),
+    ]);
+
+    const resolved = await createBundledLoader().resolve(ref);
+
+    expect(resolved?.stories).toEqual([
+      {
+        path: "(bundled)/colors-fyskc7pf.json",
+        definition: { noun: "color" },
+      },
+    ]);
+    expect(resolved?.version).toBe("1.2.3");
+  });
+
+  it("does not serve package manifests as stories", async () => {
+    stubEmbeddedFiles([
+      blob("button.ttl", TTL),
+      blob("package.json", JSON.stringify({ version: "2.0.0" })),
+      blob("package-deadbeef.json", JSON.stringify({ version: "3.0.0" })),
+    ]);
+
+    const resolved = await createBundledLoader().resolve(ref);
+
+    expect(resolved?.stories).toEqual([]);
+  });
+
+  it("warns and skips a story blob with invalid JSON instead of crashing", async () => {
+    stubEmbeddedFiles([
+      blob("button.ttl", TTL),
+      blob("good-a1b2c3d4.json", JSON.stringify({ noun: "color" })),
+      blob("broken-a1b2c3d4.json", "{ not json"),
+    ]);
+
+    const resolved = await createBundledLoader().resolve(ref);
+
+    expect(resolved?.stories).toHaveLength(1);
+    expect(resolved?.stories.at(0)?.definition).toEqual({ noun: "color" });
+    expect(stderrText()).toContain("broken-a1b2c3d4.json");
+  });
+
+  it("warns and skips an unreadable story blob", async () => {
+    stubEmbeddedFiles([
+      blob("button.ttl", TTL),
+      corruptBlob("story-a1b2c3d4.json"),
+    ]);
+
+    const resolved = await createBundledLoader().resolve(ref);
+
+    expect(resolved?.stories).toEqual([]);
+    expect(stderrText()).toContain("story-a1b2c3d4.json");
+    expect(stderrText()).toContain("embedded blob unreadable");
+  });
+
+  it("resolves a stories-only bundle with no TTL graphs", async () => {
+    stubEmbeddedFiles([
+      blob("colors-fyskc7pf.json", JSON.stringify({ noun: "color" })),
+    ]);
+
+    const resolved = await createBundledLoader().resolve(ref);
+
+    expect(resolved).toBeDefined();
+    expect(resolved?.graphs).toEqual([]);
+    expect(resolved?.stories).toHaveLength(1);
+  });
+
+  it("returns undefined when no TTL or story content is embedded", async () => {
+    stubEmbeddedFiles([
+      blob("template-a1b2c3d4.ejs", "<%= name %>"),
+      blob("skill-a1b2c3d4.md", "# Skill"),
+    ]);
+
+    const resolved = await createBundledLoader().resolve(ref);
+
+    expect(resolved).toBeUndefined();
+  });
+
+  it("warns on a corrupt package manifest and falls back to 0.0.0", async () => {
+    stubEmbeddedFiles([
+      blob("button.ttl", TTL),
+      blob("package-deadbeef.json", "{ not json"),
+    ]);
+
+    const resolved = await createBundledLoader().resolve(ref);
+
+    expect(resolved?.version).toBe("0.0.0");
+    expect(stderrText()).toContain("package-deadbeef.json");
+  });
+
+  it("rejects JSON blobs whose basename is not a package manifest", async () => {
+    stubEmbeddedFiles([
+      blob("button.ttl", TTL),
+      blob("mypackage.json", JSON.stringify({ version: "9.9.9" })),
+      blob("package-lock.json", JSON.stringify({ version: "8.8.8" })),
+      blob("packages.json", JSON.stringify({ version: "7.7.7" })),
+    ]);
+
+    const resolved = await createBundledLoader().resolve(ref);
+    expect(resolved?.version).toBe("0.0.0");
+  });
+
+  it("warns on an invalid semver version and keeps looking", async () => {
+    stubEmbeddedFiles([
+      blob("button.ttl", TTL),
+      blob("package-aaaaaaaa.json", JSON.stringify({ version: "not-semver" })),
+      blob("package-bbbbbbbb.json", JSON.stringify({ version: "3.4.5" })),
+    ]);
+
+    const resolved = await createBundledLoader().resolve(ref);
+
+    expect(resolved?.version).toBe("3.4.5");
+    expect(stderrText()).toContain('invalid semver "not-semver"');
+  });
+
+  it("caches the resolved package until the cache is reset", async () => {
+    stubEmbeddedFiles([
+      blob("button.ttl", TTL),
+      blob("package.json", JSON.stringify({ version: "1.0.0" })),
+    ]);
+
+    const first = await createBundledLoader().resolve(ref);
+    expect(first?.version).toBe("1.0.0");
+
+    // New fixture without reset — cached result still returned.
+    stubEmbeddedFiles([
+      blob("other.ttl", TTL),
+      blob("package.json", JSON.stringify({ version: "5.0.0" })),
+    ]);
+    const second = await createBundledLoader().resolve(ref);
+    expect(second).toBe(first);
+
+    // After reset the loader re-reads the embedded files.
+    resetBundledLoaderCache();
+    const third = await createBundledLoader().resolve(ref);
+    expect(third?.version).toBe("5.0.0");
+    expect(third).not.toBe(first);
+  });
+});

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

@@ -0,0 +1,206 @@
+/**
+ * Bundled package loader for compiled binaries.
+ *
+ * Resolves semantic content from `Bun.embeddedFiles` — the TTL graphs
+ * and story-pack JSON embedded into the compiled binary via the build
+ * command. Skills are not embedded; this loader reports `skills: []`.
+ *
+ * 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 and story content,
+ * and the same cached package is returned for every ref this loader
+ * resolves.
+ * Note that repeated loads are NOT fully deduplicated by the store:
+ * Oxigraph applies set semantics to ground triples, but blank nodes are
+ * re-minted on every parse, so content loaded both here and by a
+ * higher-precedence loader can produce duplicated blank-node subgraphs.
+ * The orchestrator's first-loader-wins precedence (local > git >
+ * bundled) is what keeps individual packages from double-loading.
+ *
+ * @note Impure — reads embedded blobs.
+ */
+
+import { basename } from "node:path";
+import type { PackageRef } from "../../refs/operations/parseRef.js";
+import type {
+  GraphContent,
+  PackageLoader,
+  SemanticPackage,
+  StoryFileEntry,
+} from "../semanticPackage.js";
+
+// ---------------------------------------------------------------------------
+// State
+// ---------------------------------------------------------------------------
+
+/** Cached result — embedded content is immutable, no need to re-read. */
+let cached: SemanticPackage | undefined;
+
+/**
+ * Reset the module-level cache. Test-only: lets suites exercise the loader
+ * against different `Bun.embeddedFiles` fixtures without module isolation.
+ */
+export function resetBundledLoaderCache(): void {
+  cached = undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Embedded package manifest basename: exactly `package.json`, or
+ * `package-<hash>.json` where `<hash>` is bun's content hash suffix.
+ */
+const PACKAGE_MANIFEST_PATTERN = /^package(?:-[0-9a-f]{6,64})?\.json$/i;
+
+/**
+ * Semver 2.0.0 validation (semver.org's suggested pattern).
+ */
+const SEMVER_PATTERN =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+
+/**
+ * Whether a blob name is an embedded package manifest — strict basename
+ * match, so unrelated JSON blobs (e.g. `mypackage.json`) are not misread.
+ */
+function isPackageManifest(name: string): boolean {
+  return PACKAGE_MANIFEST_PATTERN.test(basename(name));
+}
+
+/**
+ * Emit a loader warning on stderr (safe for both CLI and MCP stdio use).
+ */
+function warn(message: string): void {
+  process.stderr.write(`Warning: bundled loader: ${message}\n`);
+}
+
+// ---------------------------------------------------------------------------
+// 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);
+      const stories = await readEmbeddedStories(blobs);
+      if (graphs.length === 0 && stories.length === 0) return undefined;
+
+      const version = await readEmbeddedVersion(blobs);
+
+      cached = {
+        name: "(bundled)",
+        version,
+        source: "bundled",
+        graphs,
+        skills: [],
+        stories,
+      };
+
+      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 (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      warn(`skipping unreadable embedded graph "${blob.name}": ${reason}`);
+    }
+  }
+
+  return graphs;
+}
+
+// ---------------------------------------------------------------------------
+// Story reading
+// ---------------------------------------------------------------------------
+
+/**
+ * Read story-pack definitions from embedded `.json` blobs.
+ *
+ * The build's story-assets plugin makes `stories/*.json` the only JSON
+ * embedded as file assets (see storyAssetsPlugin.ts), so every `.json`
+ * blob not named like a package manifest is a story file. Mirrors the
+ * local loader: a blob that cannot be read or parsed warns on stderr
+ * and is skipped — one bad file cannot break boot. Definitions are
+ * shape-validated later by the story-pack compiler.
+ */
+async function readEmbeddedStories(
+  blobs: ReadonlyArray<Blob & { name: string }>,
+): Promise<StoryFileEntry[]> {
+  const stories: StoryFileEntry[] = [];
+
+  for (const blob of blobs) {
+    if (!blob.name.endsWith(".json") || isPackageManifest(blob.name)) continue;
+
+    try {
+      stories.push({
+        path: `(bundled)/${blob.name}`,
+        definition: JSON.parse(await blob.text()),
+      });
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      warn(`skipping invalid embedded story "${blob.name}": ${reason}`);
+    }
+  }
+
+  return stories;
+}
+
+// ---------------------------------------------------------------------------
+// Version reading
+// ---------------------------------------------------------------------------
+
+async function readEmbeddedVersion(
+  blobs: ReadonlyArray<Blob & { name: string }>,
+): Promise<string> {
+  for (const blob of blobs) {
+    if (!isPackageManifest(blob.name)) continue;
+
+    try {
+      const text = await blob.text();
+      const parsed = JSON.parse(text) as { version?: unknown };
+      if (typeof parsed.version !== "string") continue;
+      if (!SEMVER_PATTERN.test(parsed.version)) {
+        warn(
+          `ignoring invalid semver "${parsed.version}" in embedded manifest "${blob.name}"`,
+        );
+        continue;
+      }
+      return parsed.version;
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      warn(`skipping corrupt embedded manifest "${blob.name}": ${reason}`);
+    }
+  }
+
+  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, stories } = readPackageDir(dir);
+      return { name: ref.pkg, version, source: "git", graphs, skills, stories };
+    },
+  };
+}

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

@@ -0,0 +1,9 @@
+/** @module Semantic package loaders — local, git, and bundled resolution. */
+
+export {
+  default as createBundledLoader,
+  resetBundledLoaderCache,
+} 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,87 @@
+/**
+ * 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, stories } = readPackageDir(ref.path);
+        return {
+          name: ref.pkg,
+          version,
+          source: "local",
+          graphs,
+          skills,
+          stories,
+        };
+      }
+
+      // All ref kinds → try node_modules walk
+      const dir = findPackageDir(ref.pkg);
+      if (!dir) return undefined;
+
+      const { version, graphs, skills, stories } = readPackageDir(dir);
+      return {
+        name: ref.pkg,
+        version,
+        source: "local",
+        graphs,
+        skills,
+        stories,
+      };
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// 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;
+}