plgg-bundle 0.0.3 → 0.0.6

package/bin/relocate.mjs

@@ -3,14 +3,15 @@
 // These tools run their `src/**/*.ts` entry directly and rely on Node stripping
 // types on load. Node refuses to strip types for `.ts` files under
 // `node_modules`, so a registry-installed tool cannot run in place. This helper
-// copies the package to a version-stamped dir OUTSIDE `node_modules` (with the
-// tool's own deps reachable via a `node_modules` symlink) and re-execs the copy
-// there. On a monorepo `file:` link the package realpath is already outside
-// `node_modules`, so it is a no-op.
+// copies the package to a per-(version, install-location) dir OUTSIDE
+// `node_modules` (with the tool's own deps reachable via a `node_modules`
+// symlink) and re-execs the copy there. On a monorepo `file:` link the package
+// realpath is already outside `node_modules`, so it is a no-op.
 //
 // Plain `.mjs`, Node built-ins only — it runs at process entry, before any
 // resolver hook is registered.
 import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import {
   cpSync,
   existsSync,
@@ -54,14 +55,25 @@ export const relocateOutOfNodeModules = (
       "utf8",
     ),
   );
+  // The node_modules that CONTAINS this package holds its deps (npm hoists
+  // there). Key the relocation dir by that location too — two installs of the
+  // same version from different trees (e.g. a publish smoke's scratch install
+  // and a real consumer) must NOT share a copy, or one inherits the other's
+  // stale (possibly deleted) deps symlink.
+  const depsNodeModules = dirname(pkgRoot);
+  const tag = createHash("sha1")
+    .update(depsNodeModules)
+    .digest("hex")
+    .slice(0, 12);
   const dest = join(
     tmpdir(),
-    `plgg-relocate-${pkg.name}-${pkg.version}`,
+    `plgg-relocate-${pkg.name}-${pkg.version}-${tag}`,
   );
   const ready = join(
     dest,
     ".plgg-relocate-ready",
   );
+  const link = join(dest, "node_modules");
 
   if (!existsSync(ready)) {
     rmSync(dest, {
@@ -81,19 +93,16 @@ export const relocateOutOfNodeModules = (
       join(pkgRoot, "package.json"),
       join(dest, "package.json"),
     );
-    // The tool's own deps (typescript; plgg for plgg-test) live in the
-    // node_modules that CONTAINS this package (npm hoists there). Symlink it so
-    // resolution from the relocated copy finds them.
-    try {
-      symlinkSync(
-        dirname(pkgRoot),
-        join(dest, "node_modules"),
-        "dir",
-      );
-    } catch {
-      // A pre-existing symlink from a concurrent run is fine.
-    }
-    writeFileSync(ready, "");
+    writeFileSync(ready, depsNodeModules + "\n");
+  }
+  // (Re)create the deps symlink every run so it always points at the CURRENT
+  // node_modules: a cached copy from a prior run may hold a symlink to a tree
+  // that has since been removed (a publish smoke's scratch install) or moved.
+  rmSync(link, { force: true });
+  try {
+    symlinkSync(depsNodeModules, link, "dir");
+  } catch {
+    // A concurrent run created it first; its target is identical.
   }
 
   const child = spawnSync(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plgg-bundle",
-  "version": "0.0.3",
+  "version": "0.0.6",
   "description": "In-house minimal library bundler for the plgg monorepo (ESM+CJS dual output, per-file .d.ts tree), zero new dependencies — reuses the project's own TypeScript, no native binding.",
   "type": "module",
   "files": [
@@ -23,6 +23,6 @@
   },
   "devDependencies": {
     "@types/node": "^25.6.0",
-    "plgg-test": "^0.0.4"
+    "plgg-test": "^0.0.5"
   }
 }

package/src/domain/usecase/collectModules.spec.ts

@@ -0,0 +1,441 @@
+import {
+  test,
+  check,
+  all,
+  toBe,
+} from "plgg-test";
+import {
+  mkdirSync,
+  mkdtempSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { collectModules } from "plgg-bundle/domain/usecase/collectModules";
+import {
+  emitCjsBundle,
+  emitEsmBundle,
+} from "plgg-bundle/domain/usecase/emitBundle";
+
+test("collectModules records external specifiers without walking them", () => {
+  const root = mkdtempSync(
+    join(tmpdir(), "plgg-bundle-collect-ext-"),
+  );
+  try {
+    const entry = join(root, "src", "main.ts");
+    mkdirSync(join(root, "src"), {
+      recursive: true,
+    });
+    writeFileSync(
+      entry,
+      'import { readFileSync } from "node:fs";\nexport const read = readFileSync;\n',
+    );
+    const graph = collectModules({
+      entryFile: entry,
+      root,
+      aliasPrefix: "app",
+      aliasSrcRoot: join(root, "src"),
+      external: /^node:/,
+    });
+    return all([
+      check(graph.modules.length, toBe(1)),
+      check(
+        graph.modules[0]?.externals[0],
+        toBe("node:fs"),
+      ),
+    ]);
+  } finally {
+    rmSync(root, {
+      recursive: true,
+      force: true,
+    });
+  }
+});
+
+test("collectModules throws on an unresolvable non-external specifier", () => {
+  const root = mkdtempSync(
+    join(
+      tmpdir(),
+      "plgg-bundle-collect-missing-",
+    ),
+  );
+  try {
+    const entry = join(root, "src", "main.ts");
+    mkdirSync(join(root, "src"), {
+      recursive: true,
+    });
+    writeFileSync(entry, 'import "missing";\n');
+    return check(
+      rejects(() =>
+        collectModules({
+          entryFile: entry,
+          root,
+          aliasPrefix: "app",
+          aliasSrcRoot: join(root, "src"),
+          external: /^node:/,
+        }),
+      ),
+      toBe(true),
+    );
+  } finally {
+    rmSync(root, {
+      recursive: true,
+      force: true,
+    });
+  }
+});
+
+test("collectModules inlines an installed prebundled dist entry without resolving its internal registry requires", () => {
+  const root = mkdtempSync(
+    join(tmpdir(), "plgg-bundle-collect-"),
+  );
+  try {
+    const entry = join(root, "src", "main.ts");
+    const dep = join(
+      root,
+      "node_modules",
+      "dep",
+      "dist",
+      "index.es.js",
+    );
+    const plgg = join(
+      root,
+      "node_modules",
+      "plgg",
+      "dist",
+      "index.es.js",
+    );
+    mkdirSync(join(root, "src"), {
+      recursive: true,
+    });
+    mkdirSync(
+      join(root, "node_modules", "dep", "dist"),
+      {
+        recursive: true,
+      },
+    );
+    mkdirSync(
+      join(root, "node_modules", "plgg", "dist"),
+      {
+        recursive: true,
+      },
+    );
+    writeFileSync(
+      entry,
+      'import dep from "dep";\nexport const value = dep.value;\n',
+    );
+    writeFileSync(
+      dep,
+      [
+        'import * as __ext0 from "plgg";',
+        'const __externals = { "plgg": __ext0 };',
+        "const __modules = {",
+        '"src/index.ts": function (module, exports, require) {',
+        '  exports.value = require("src/internal.ts").value;',
+        "},",
+        '"src/internal.ts": function (module, exports, require) {',
+        "  exports.value = __externals.plgg.external;",
+        "}",
+        "};",
+        'const __entry = __modules["src/index.ts"];',
+        "export default { value: __entry };",
+      ].join("\n"),
+    );
+    writeFileSync(
+      plgg,
+      "export const external = 1;\n",
+    );
+
+    const graph = collectModules({
+      entryFile: entry,
+      root,
+      aliasPrefix: "app",
+      aliasSrcRoot: join(root, "src"),
+      external: /^node:/,
+      resolve: (specifier, _fromFile) =>
+        specifier === "dep"
+          ? dep
+          : specifier === "plgg"
+            ? plgg
+            : undefined,
+    });
+    const depModule = graph.modules.find(
+      (m) =>
+        m.id ===
+        "node_modules/dep/dist/index.es.js",
+    );
+    return all([
+      check(graph.modules.length, toBe(3)),
+      check(
+        depModule?.code.includes(
+          'require("src/internal.ts")',
+        ),
+        toBe(true),
+      ),
+      check(
+        depModule?.code.includes(
+          'require("node_modules/plgg/dist/index.es.js")',
+        ),
+        toBe(true),
+      ),
+    ]);
+  } finally {
+    rmSync(root, {
+      recursive: true,
+      force: true,
+    });
+  }
+});
+
+test("collectModules resolves node_modules source files without dist-registry filtering", () => {
+  const root = mkdtempSync(
+    join(tmpdir(), "plgg-bundle-collect-src-"),
+  );
+  try {
+    const entry = join(root, "src", "main.ts");
+    const dep = join(
+      root,
+      "node_modules",
+      "dep",
+      "src",
+      "index.ts",
+    );
+    const internal = join(
+      root,
+      "node_modules",
+      "dep",
+      "src",
+      "internal.ts",
+    );
+    writeImportFixture(entry, dep, internal);
+    const graph = collectModules({
+      entryFile: entry,
+      root,
+      aliasPrefix: "app",
+      aliasSrcRoot: join(root, "src"),
+      external: /^node:/,
+      resolve: importFixtureResolver(
+        dep,
+        internal,
+      ),
+    });
+    return check(graph.modules.length, toBe(3));
+  } finally {
+    rmSync(root, {
+      recursive: true,
+      force: true,
+    });
+  }
+});
+
+test("collectModules resolves non-js dist source files without dist-registry filtering", () => {
+  const root = mkdtempSync(
+    join(tmpdir(), "plgg-bundle-collect-mjs-"),
+  );
+  try {
+    const entry = join(root, "src", "main.ts");
+    const dep = join(
+      root,
+      "node_modules",
+      "dep",
+      "dist",
+      "index.ts",
+    );
+    const internal = join(
+      root,
+      "node_modules",
+      "dep",
+      "dist",
+      "internal.ts",
+    );
+    writeImportFixture(entry, dep, internal);
+    const graph = collectModules({
+      entryFile: entry,
+      root,
+      aliasPrefix: "app",
+      aliasSrcRoot: join(root, "src"),
+      external: /^node:/,
+      resolve: importFixtureResolver(
+        dep,
+        internal,
+      ),
+    });
+    return check(graph.modules.length, toBe(3));
+  } finally {
+    rmSync(root, {
+      recursive: true,
+      force: true,
+    });
+  }
+});
+
+test("an app bundling two dists with identical inner module paths keeps each dist's externals resolvable", () => {
+  // Regression for the plggmatic blank-page defect:
+  // pkg-a and pkg-b are plgg-bundle ESM dists whose
+  // inner registries both key "src/index.ts", and
+  // pkg-b requires pkg-a through its inner
+  // __externals table. The outer rewrite must keep
+  // that table's key in step with the rewritten
+  // require, or pkg-b's inner lookup falls into the
+  // async import fallback and yields a Promise where
+  // a namespace is expected.
+  const root = mkdtempSync(
+    join(tmpdir(), "plgg-bundle-collect-nested-"),
+  );
+  try {
+    const entry = join(root, "src", "main.ts");
+    const pkgA = join(
+      root,
+      "node_modules",
+      "pkg-a",
+      "dist",
+      "index.es.js",
+    );
+    const pkgB = join(
+      root,
+      "node_modules",
+      "pkg-b",
+      "dist",
+      "index.es.js",
+    );
+    mkdirSync(join(root, "src"), {
+      recursive: true,
+    });
+    mkdirSync(join(pkgA, ".."), {
+      recursive: true,
+    });
+    mkdirSync(join(pkgB, ".."), {
+      recursive: true,
+    });
+    writeFileSync(
+      entry,
+      [
+        'import { box } from "pkg-a";',
+        'import { useBox } from "pkg-b";',
+        "export const direct = box(1);",
+        "export const viaB = useBox();",
+      ].join("\n"),
+    );
+    // Both dists come from the real emitter, so the
+    // fixture cannot drift from the emitted shape.
+    writeFileSync(
+      pkgA,
+      emitEsmBundle(
+        {
+          entryId: "src/index.ts",
+          modules: [
+            {
+              id: "src/index.ts",
+              code: "exports.box = (v) => v * 2;",
+              externals: [],
+            },
+          ],
+        },
+        ["box"],
+      ),
+    );
+    writeFileSync(
+      pkgB,
+      emitEsmBundle(
+        {
+          entryId: "src/index.ts",
+          modules: [
+            {
+              id: "src/index.ts",
+              code: 'exports.useBox = () => require("pkg-a").box(21);',
+              externals: ["pkg-a"],
+            },
+          ],
+        },
+        ["useBox"],
+      ),
+    );
+    const graph = collectModules({
+      entryFile: entry,
+      root,
+      aliasPrefix: "app",
+      aliasSrcRoot: join(root, "src"),
+      external: /^node:/,
+      resolve: (specifier, _fromFile) =>
+        specifier === "pkg-a"
+          ? pkgA
+          : specifier === "pkg-b"
+            ? pkgB
+            : undefined,
+    });
+    const mod: {
+      exports: Record<string, unknown>;
+    } = {
+      exports: {},
+    };
+    new Function(
+      "module",
+      "exports",
+      "require",
+      emitCjsBundle(graph),
+    )(mod, mod.exports, () => ({}));
+    return all([
+      check(mod.exports.direct, toBe(2)),
+      check(mod.exports.viaB, toBe(42)),
+    ]);
+  } finally {
+    rmSync(root, {
+      recursive: true,
+      force: true,
+    });
+  }
+});
+
+const writeImportFixture = (
+  entry: string,
+  dep: string,
+  internal: string,
+): void => {
+  mkdirSync(join(entry, ".."), {
+    recursive: true,
+  });
+  mkdirSync(join(dep, ".."), { recursive: true });
+  mkdirSync(join(internal, ".."), {
+    recursive: true,
+  });
+  writeFileSync(
+    entry,
+    'import { value } from "dep";\nexport const out = value;\n',
+  );
+  writeFileSync(
+    dep,
+    'import { value } from "src/internal.ts";\nexport { value };\n',
+  );
+  writeFileSync(
+    internal,
+    "export const value = 1;\n",
+  );
+};
+
+const importFixtureResolver =
+  (
+    dep: string,
+    internal: string,
+  ): ((
+    specifier: string,
+    fromFile: string,
+  ) => string | undefined) =>
+  (specifier, _fromFile) =>
+    specifier === "dep"
+      ? dep
+      : specifier === "src/internal.ts"
+        ? internal
+        : undefined;
+
+const rejects = (f: () => unknown): boolean => {
+  try {
+    f();
+    return false;
+  } catch (e) {
+    return (
+      e instanceof Error &&
+      e.message.startsWith("ResolveError")
+    );
+  }
+};

package/src/domain/usecase/collectModules.ts

@@ -135,7 +135,10 @@ const linkModule = (
   cjs: string,
   acc: Map<string, Module>,
 ): ReadonlyArray<string> => {
-  const specifiers = requireSpecifiers(cjs);
+  const specifiers = inlineRequireSpecifiers(
+    file,
+    cjs,
+  );
   const externals: string[] = [];
   const deps: string[] = [];
   let rewritten = cjs;
@@ -156,6 +159,13 @@ const linkModule = (
       spec,
       idOf(ctx.root, resolved),
     );
+    if (isInstalledDist(file)) {
+      rewritten = replaceExternalKey(
+        rewritten,
+        spec,
+        idOf(ctx.root, resolved),
+      );
+    }
   }
   acc.set(id, {
     id,
@@ -165,6 +175,63 @@ const linkModule = (
   return deps;
 };
 
+/**
+ * Literal requires that belong to the OUTER graph walk.
+ * Registry-installed plgg-family packages ship
+ * pre-bundled dist entries whose internal module table
+ * still contains strings like `require("src/index.ts")`.
+ * Those are parameters of the INNER registry runtime and
+ * must not be resolved or rewritten by this app bundle.
+ * Real top-level externals in that dist file remain, e.g.
+ * `require("plgg")`, and are still inlined by the app
+ * graph.
+ */
+const inlineRequireSpecifiers = (
+  file: string,
+  cjs: string,
+): ReadonlyArray<string> => {
+  const specifiers = requireSpecifiers(cjs);
+  if (!isInstalledDist(file)) {
+    return specifiers;
+  }
+  const internal = bundledModuleIds(cjs);
+  return specifiers.filter(
+    (spec) => !internal.has(spec),
+  );
+};
+
+/**
+ * Whether a file is a registry-installed built JS entry.
+ * Source packages under the monorepo are never matched.
+ */
+const isInstalledDist = (
+  file: string,
+): boolean => {
+  const normalized = file.split("\\").join("/");
+  return (
+    normalized.includes("/node_modules/") &&
+    normalized.includes("/dist/") &&
+    normalized.endsWith(".js")
+  );
+};
+
+/**
+ * Module ids declared inside a plgg-bundle emitted
+ * registry object: `"src/x.ts": function (...) { ... }`.
+ */
+const bundledModuleIds = (
+  cjs: string,
+): ReadonlySet<string> =>
+  new Set(
+    [
+      ...cjs.matchAll(
+        /["']([^"']+)["']\s*:\s*function\s*\(/g,
+      ),
+    ].flatMap((m) =>
+      m[1] === undefined ? [] : [m[1]],
+    ),
+  );
+
 /**
  * Read a source file, re-throwing with context.
  */
@@ -209,6 +276,29 @@ const requireSpecifiers = (
     m[1] === undefined ? [] : [m[1]],
   );
 
+/**
+ * Rewrite an inlined dist's inner `__externals` table
+ * key from the original specifier to the outer module
+ * id. A plgg-bundle ESM dist resolves an external
+ * required inside its inner module bodies through this
+ * table; {@link replaceRequire} rewrites those bodies'
+ * `require("<spec>")` calls to the outer id, so the key
+ * must follow or the inner lookup misses and falls into
+ * the transpiled dynamic-import fallback — a Promise
+ * where the consumer expects a namespace ("plgg_1.box
+ * is not a function"). Matches the exact
+ * `"<spec>": __extN` shape the TS printer emits for the
+ * table, so ordinary code never collides with it.
+ */
+const replaceExternalKey = (
+  cjs: string,
+  spec: string,
+  id: string,
+): string =>
+  cjs
+    .split(`${JSON.stringify(spec)}: __ext`)
+    .join(`${JSON.stringify(id)}: __ext`);
+
 /**
  * Rewrite every `require("spec")` occurrence to
  * `require("id")`. Operates on the exact specifier

package/src/domain/usecase/discoverWorkspace.spec.ts

@@ -4,6 +4,13 @@ import {
   all,
   toBe,
 } from "plgg-test";
+import {
+  mkdirSync,
+  mkdtempSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { discoverWorkspace } from "plgg-bundle/domain/usecase/discoverWorkspace";
 
@@ -61,3 +68,107 @@ test("discoverWorkspace sorts longest-name first (so plgg-view beats plgg)", ()
   );
   return check(iView < iCore, toBe(true));
 });
+
+test("discoverWorkspace finds dist-only packages installed under node_modules", () => {
+  const root = fixtureRoot();
+  try {
+    const app = join(root, "packages", "app");
+    writePackage(app, "app", true);
+    writePackage(
+      join(app, "node_modules", "plgg"),
+      "plgg",
+      false,
+    );
+    const found = discoverWorkspace(app).find(
+      (p) => p.name === "plgg",
+    );
+    return all([
+      check(found?.kind, toBe("dist")),
+      check(
+        found?.exports.get("."),
+        toBe("./dist/index.es.js"),
+      ),
+    ]);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("discoverWorkspace keeps a sibling source package before an installed duplicate", () => {
+  const root = fixtureRoot();
+  try {
+    const app = join(root, "packages", "app");
+    writePackage(app, "app", true);
+    writePackage(
+      join(root, "packages", "plgg"),
+      "plgg",
+      true,
+    );
+    writePackage(
+      join(app, "node_modules", "plgg"),
+      "plgg",
+      false,
+    );
+    const found = discoverWorkspace(app).find(
+      (p) => p.name === "plgg",
+    );
+    return check(found?.kind, toBe("source"));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("discoverWorkspace finds installed deps of a sibling source package", () => {
+  const root = fixtureRoot();
+  try {
+    const app = join(root, "packages", "app");
+    writePackage(app, "app", true);
+    const local = join(root, "packages", "local");
+    writePackage(local, "local", true);
+    writePackage(
+      join(local, "node_modules", "plgg-cms"),
+      "plgg-cms",
+      false,
+    );
+    const found = discoverWorkspace(app).find(
+      (p) => p.name === "plgg-cms",
+    );
+    return check(found?.kind, toBe("dist"));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+const fixtureRoot = (): string =>
+  mkdtempSync(
+    join(tmpdir(), "plgg-bundle-discover-"),
+  );
+
+const writePackage = (
+  dir: string,
+  name: string,
+  source: boolean,
+): void => {
+  mkdirSync(source ? join(dir, "src") : join(dir, "dist"), {
+    recursive: true,
+  });
+  writeFileSync(
+    join(dir, "package.json"),
+    JSON.stringify(
+      {
+        name,
+        type: "module",
+        exports: {
+          import: {
+            default: "./dist/index.es.js",
+          },
+          require: {
+            default: "./dist/index.cjs.js",
+          },
+        },
+      },
+      null,
+      2,
+    ),
+  );
+};

package/src/domain/usecase/discoverWorkspace.ts

@@ -7,38 +7,65 @@ import {
 import { join, dirname } from "plgg-bundle/vendors/nodePath";
 
 /**
- * A workspace sibling the app bundler can INLINE from
- * source: its package `name`, its `dir`, and the map from
- * each public export subpath (`"."`, `"./client"`, …) to
- * the `import.default` dist path declared in its
- * `package.json` `exports`. The app resolver reverses
- * that dist path to the entry's source file (so the
- * `./style` → `dist/styleEntry.es.js` → `src/styleEntry`
- * rename is honoured), and falls back to a self-alias
- * `name/<path>` → `src/<path>` for non-export internal
- * imports.
- */
-export type WorkspacePackage = Readonly<{
+ * A package the app bundler can INLINE. Monorepo
+ * siblings are inlined from `src`; registry-installed
+ * packages usually ship only `dist`, so the resolver
+ * inlines their built ESM entry instead.
+ */
+export type WorkspacePackage =
+  | SourceWorkspacePackage
+  | DistWorkspacePackage;
+
+/**
+ * A source package, usually a sibling under `packages/`.
+ * Its public export subpaths are reversed from
+ * `exports` dist paths back to `src` entries.
+ */
+export type SourceWorkspacePackage = Readonly<{
+  kind: "source";
+  name: string;
+  dir: string;
+  srcDir: string;
+  /** export subpath (`"."` | `"./x"`) → dist default. */
+  exports: ReadonlyMap<string, string>;
+}>;
+
+/**
+ * A dist package, usually installed under the app's
+ * `node_modules`. It has no source in the consumer tree,
+ * so public export subpaths resolve to built ESM files.
+ */
+export type DistWorkspacePackage = Readonly<{
+  kind: "dist";
   name: string;
   dir: string;
+  distDir: string;
   /** export subpath (`"."` | `"./x"`) → dist default. */
   exports: ReadonlyMap<string, string>;
 }>;
 
 /**
- * Discover every sibling package under the directory that
- * holds `packageRoot` (the monorepo `packages/` dir) —
- * each entry that has a `package.json` with a `name`.
+ * Discover inlineable packages visible from `packageRoot`:
+ * sibling packages under the directory that holds
+ * `packageRoot`, plus packages installed in this package's
+ * own `node_modules` and in sibling source packages'
+ * `node_modules`. Siblings are listed first and win on
+ * duplicate names so monorepo builds keep reading source.
  * Sorted longest-name-first so a later prefix match picks
- * `plgg-view` over `plgg`. Throws on a read/parse failure.
+ * `plgg-view` over `plgg`.
  */
 export const discoverWorkspace = (
   packageRoot: string,
 ): ReadonlyArray<WorkspacePackage> => {
   const siblingsDir = dirname(packageRoot);
-  return readdirSync(siblingsDir)
-    .map((name) => join(siblingsDir, name))
-    .filter(isPackageDir)
+  const siblings = packageDirsIn(siblingsDir);
+  return uniqueByName([
+    ...siblings,
+    ...packageDirsIn(join(packageRoot, "node_modules")),
+    ...siblings.flatMap((dir) =>
+      packageDirsIn(join(dir, "node_modules")),
+    ),
+  ])
     .map(readPackage)
     .flatMap((p) => (p === undefined ? [] : [p]))
     .sort(
@@ -47,8 +74,61 @@ export const discoverWorkspace = (
 };
 
 /**
- * Whether a path is a directory holding a
- * `package.json`.
+ * Direct package dirs under `dir`, including scoped
+ * `@scope/name` packages. Missing directories simply
+ * contribute no packages.
+ */
+const packageDirsIn = (
+  dir: string,
+): ReadonlyArray<string> =>
+  existsSync(dir)
+    ? readdirSync(dir).flatMap((name) =>
+        childPackageDirs(join(dir, name)),
+      )
+    : [];
+
+/**
+ * The package dirs represented by one child of a package
+ * collection directory. A scope directory fans out one
+ * level; ordinary package directories are returned as-is.
+ */
+const childPackageDirs = (
+  dir: string,
+): ReadonlyArray<string> => {
+  if (!statSync(dir).isDirectory()) {
+    return [];
+  }
+  if (isPackageDir(dir)) {
+    return [dir];
+  }
+  return readdirSync(dir)
+    .map((name) => join(dir, name))
+    .filter(isPackageDir);
+};
+
+/**
+ * Keep the first directory for each package name. The
+ * caller supplies siblings before node_modules, so a local
+ * source package beats an installed copy.
+ */
+const uniqueByName = (
+  dirs: ReadonlyArray<string>,
+): ReadonlyArray<string> => {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const dir of dirs) {
+    const name = packageName(dir);
+    if (name === undefined || seen.has(name)) {
+      continue;
+    }
+    seen.add(name);
+    out.push(dir);
+  }
+  return out;
+};
+
+/**
+ * Whether a path is a directory holding a package.json.
  */
 const isPackageDir = (dir: string): boolean =>
   statSync(dir).isDirectory() &&
@@ -66,9 +146,44 @@ const readPackage = (
     join(dir, "package.json"),
   );
   const name = pkg["name"];
-  return typeof name === "string"
-    ? { name, dir, exports: exportMap(pkg) }
-    : undefined;
+  if (typeof name !== "string") {
+    return undefined;
+  }
+  const srcDir = join(dir, "src");
+  if (existsSync(srcDir)) {
+    return {
+      kind: "source",
+      name,
+      dir,
+      srcDir,
+      exports: exportMap(pkg),
+    };
+  }
+  const distDir = join(dir, "dist");
+  if (existsSync(distDir)) {
+    return {
+      kind: "dist",
+      name,
+      dir,
+      distDir,
+      exports: exportMap(pkg),
+    };
+  }
+  return undefined;
+};
+
+/**
+ * Read only the package name for de-duplication.
+ */
+const packageName = (
+  dir: string,
+): string | undefined => {
+  if (!isPackageDir(dir)) {
+    return undefined;
+  }
+  const pkg = parseJson(join(dir, "package.json"));
+  const name = pkg["name"];
+  return typeof name === "string" ? name : undefined;
 };
 
 /**

package/src/domain/usecase/resolveWorkspaceSpecifier.spec.ts

@@ -4,6 +4,13 @@ import {
   all,
   toBe,
 } from "plgg-test";
+import {
+  mkdirSync,
+  mkdtempSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { discoverWorkspace } from "plgg-bundle/domain/usecase/discoverWorkspace";
 import { resolveWorkspaceSpecifier } from "plgg-bundle/domain/usecase/resolveWorkspaceSpecifier";
@@ -77,3 +84,93 @@ test("returns undefined for a non-workspace specifier", () =>
     check(resolve("react"), toBe(undefined)),
     check(resolve("node:fs"), toBe(undefined)),
   ]));
+
+test("resolves an installed dist-only package export to its built ESM file", () => {
+  const root = fixtureRoot();
+  try {
+    const app = join(root, "packages", "app");
+    writePackage(app, "app", true);
+    writePackage(
+      join(app, "node_modules", "plgg"),
+      "plgg",
+      false,
+    );
+    const installed = discoverWorkspace(app);
+    return check(
+      resolveWorkspaceSpecifier({
+        specifier: "plgg",
+        fromFile: join(app, "src", "main.ts"),
+        packages: installed,
+      }),
+      toBe(
+        join(
+          app,
+          "node_modules",
+          "plgg",
+          "dist",
+          "index.es.js",
+        ),
+      ),
+    );
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("does not resolve internal paths from a dist-only installed package", () => {
+  const root = fixtureRoot();
+  try {
+    const app = join(root, "packages", "app");
+    writePackage(app, "app", true);
+    writePackage(
+      join(app, "node_modules", "plgg"),
+      "plgg",
+      false,
+    );
+    const installed = discoverWorkspace(app);
+    return check(
+      resolveWorkspaceSpecifier({
+        specifier: "plgg/Atomics/Num",
+        fromFile: join(app, "src", "main.ts"),
+        packages: installed,
+      }),
+      toBe(undefined),
+    );
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+const fixtureRoot = (): string =>
+  mkdtempSync(join(tmpdir(), "plgg-bundle-resolve-"));
+
+const writePackage = (
+  dir: string,
+  name: string,
+  source: boolean,
+): void => {
+  const codeDir = source
+    ? join(dir, "src")
+    : join(dir, "dist");
+  mkdirSync(codeDir, { recursive: true });
+  writeFileSync(join(codeDir, "index.es.js"), "");
+  writeFileSync(
+    join(dir, "package.json"),
+    JSON.stringify(
+      {
+        name,
+        type: "module",
+        exports: {
+          import: {
+            default: "./dist/index.es.js",
+          },
+          require: {
+            default: "./dist/index.cjs.js",
+          },
+        },
+      },
+      null,
+      2,
+    ),
+  );
+};

package/src/domain/usecase/resolveWorkspaceSpecifier.ts

@@ -8,11 +8,12 @@ import { type WorkspacePackage } from "plgg-bundle/domain/usecase/discoverWorksp
 
 /**
  * App-mode resolver: resolve an import specifier to an
- * absolute SOURCE file, inlining workspace siblings
- * (`plgg`, `plgg-view/client`, …) by walking their `src`
- * instead of leaving them external. This is the mirror of
- * the library externalization — the leaf app is where
- * bundling deps is correct.
+ * absolute inlineable file. Source packages
+ * (`packages/plgg`, local `file:` siblings) resolve to
+ * `src`; published packages installed in `node_modules`
+ * resolve to their built ESM `dist` export. This is the
+ * mirror of the library externalization — the leaf app is
+ * where bundling deps is correct.
  *
  * Order:
  * 1. relative (`./x`) → resolve against the importer,
@@ -75,8 +76,8 @@ const matchPackage = (
 
 /**
  * Resolve a specifier already known to belong to `pkg`:
- * a declared export subpath via the exports reversal,
- * else the internal self-alias path.
+ * a declared export subpath through the package kind,
+ * else a source package's internal self-alias path.
  */
 const resolveInPackage = (
   pkg: WorkspacePackage,
@@ -89,17 +90,42 @@ const resolveInPackage = (
           pkg.name.length + 1,
         )}`;
   const dist = pkg.exports.get(subpath);
-  return dist === undefined
+  return pkg.kind === "source"
+    ? resolveInSourcePackage(pkg, specifier, dist)
+    : resolveInDistPackage(pkg, dist);
+};
+
+/**
+ * Source packages keep the previous monorepo behavior:
+ * public exports reverse their emitted dist stem back to
+ * source; non-export self-alias paths resolve under `src`.
+ */
+const resolveInSourcePackage = (
+  pkg: WorkspacePackage & { kind: "source" },
+  specifier: string,
+  dist: string | undefined,
+): string | undefined =>
+  dist === undefined
     ? resolveSpecifier({
         specifier,
         fromFile: pkg.dir,
         aliasPrefix: pkg.name,
-        aliasSrcRoot: join(pkg.dir, "src"),
+        aliasSrcRoot: pkg.srcDir,
       })
-    : pickExisting(
-        join(pkg.dir, "src", srcStem(dist)),
-      );
-};
+    : pickExisting(join(pkg.srcDir, srcStem(dist)));
+
+/**
+ * Dist-only packages can safely resolve only declared
+ * public exports. Internal self-alias paths are not
+ * available in a consumer install.
+ */
+const resolveInDistPackage = (
+  pkg: WorkspacePackage & { kind: "dist" },
+  dist: string | undefined,
+): string | undefined =>
+  dist === undefined
+    ? undefined
+    : pickExisting(join(pkg.dir, dist));
 
 /**
  * The source stem implied by an export's dist default —