@canonical/pragma-cli 0.29.0 → 0.30.0

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

@@ -1,23 +1,32 @@
 /**
  * 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.
+ * 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 content. RDF
- * stores deduplicate triples, so this is safe when combined with
- * higher-precedence loaders that resolve individual packages.
+ * 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";
 
 // ---------------------------------------------------------------------------
@@ -27,6 +36,45 @@ import type {
 /** 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
 // ---------------------------------------------------------------------------
@@ -44,7 +92,8 @@ export default function createBundledLoader(): PackageLoader {
       if (!blobs?.length) return undefined;
 
       const graphs = await readEmbeddedGraphs(blobs);
-      if (graphs.length === 0) return undefined;
+      const stories = await readEmbeddedStories(blobs);
+      if (graphs.length === 0 && stories.length === 0) return undefined;
 
       const version = await readEmbeddedVersion(blobs);
 
@@ -54,6 +103,7 @@ export default function createBundledLoader(): PackageLoader {
         source: "bundled",
         graphs,
         skills: [],
+        stories,
       };
 
       return cached;
@@ -80,12 +130,51 @@ async function readEmbeddedGraphs(
         content,
         format: "turtle",
       });
-    } catch {}
+    } 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
 // ---------------------------------------------------------------------------
@@ -94,14 +183,23 @@ 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;
+    if (!isPackageManifest(blob.name)) continue;
 
     try {
       const text = await blob.text();
-      const parsed = JSON.parse(text) as { version?: string };
-      if (parsed.version) return parsed.version;
-    } catch {}
+      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

@@ -24,8 +24,8 @@ export default function createGitLoader(): PackageLoader {
       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 };
+      const { version, graphs, skills, stories } = readPackageDir(dir);
+      return { name: ref.pkg, version, source: "git", graphs, skills, stories };
     },
   };
 }

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

@@ -1,6 +1,9 @@
 /** @module Semantic package loaders — local, git, and bundled resolution. */
 
-export { default as createBundledLoader } from "./bundledLoader.js";
+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

@@ -28,16 +28,30 @@ 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 };
+        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 } = readPackageDir(dir);
-      return { name: ref.pkg, version, source: "local", graphs, skills };
+      const { version, graphs, skills, stories } = readPackageDir(dir);
+      return {
+        name: ref.pkg,
+        version,
+        source: "local",
+        graphs,
+        skills,
+        stories,
+      };
     },
   };
 }

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
@@ -35,6 +39,7 @@ export interface PackageDirContents {
   readonly version: string;
   readonly graphs: GraphContent[];
   readonly skills: SkillEntry[];
+  readonly stories: StoryFileEntry[];
 }
 
 /**
@@ -48,6 +53,7 @@ export default function readPackageDir(dir: string): PackageDirContents {
     version: readVersion(dir),
     graphs: readGraphs(dir),
     skills: readSkills(dir),
+    stories: readStories(dir),
   };
 }
 
@@ -87,6 +93,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",
+      }));
+    },
+  };
+}