isolate-package 1.30.0-0 → 1.31.0

package/src/lib/config.ts

@@ -1,4 +1,5 @@
 import { execFileSync } from "node:child_process";
+import { detectMonorepo } from "detect-monorepo";
 import fs from "fs-extra";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
@@ -14,7 +15,13 @@ export type IsolateConfigResolved = {
   targetPackagePath?: string;
   tsconfigPath: string;
   workspacePackages?: string[];
-  workspaceRoot: string;
+  /**
+   * Path to the workspace root, relative to the target package directory.
+   * When omitted, the workspace root is auto-detected by walking upward from
+   * the target package directory looking for a pnpm-workspace.yaml, a
+   * package.json with a `workspaces` field, or a rush.json.
+   */
+  workspaceRoot?: string;
   forceNpm: boolean;
   pickFromScripts?: string[];
   omitFromScripts?: string[];
@@ -31,7 +38,7 @@ const configDefaults: IsolateConfigResolved = {
   targetPackagePath: undefined,
   tsconfigPath: "./tsconfig.json",
   workspacePackages: undefined,
-  workspaceRoot: "../..",
+  workspaceRoot: undefined,
   forceNpm: false,
   pickFromScripts: undefined,
   omitFromScripts: undefined,
@@ -170,17 +177,35 @@ function validateConfig(config: IsolateConfig) {
  * Resolve the target package directory and workspace root directory from the
  * configuration. When targetPackagePath is set, the config is assumed to live
  * at the workspace root. Otherwise it lives in the target package directory.
+ *
+ * When `workspaceRoot` is not explicitly set, auto-detect the monorepo root by
+ * walking upward from the target package directory.
  */
 export function resolveWorkspacePaths(config: IsolateConfigResolved) {
   const targetPackageDir = config.targetPackagePath
     ? path.join(process.cwd(), config.targetPackagePath)
     : process.cwd();
 
-  const workspaceRootDir = config.targetPackagePath
-    ? process.cwd()
-    : path.join(targetPackageDir, config.workspaceRoot);
+  if (config.targetPackagePath) {
+    return { targetPackageDir, workspaceRootDir: process.cwd() };
+  }
+
+  if (config.workspaceRoot !== undefined) {
+    return {
+      targetPackageDir,
+      workspaceRootDir: path.join(targetPackageDir, config.workspaceRoot),
+    };
+  }
+
+  const detected = detectMonorepo(targetPackageDir);
+
+  if (!detected) {
+    throw new Error(
+      `Failed to auto-detect monorepo workspace root from ${targetPackageDir}. Set the 'workspaceRoot' config option explicitly.`,
+    );
+  }
 
-  return { targetPackageDir, workspaceRootDir };
+  return { targetPackageDir, workspaceRootDir: detected.rootDir };
 }
 
 export function resolveConfig(

package/src/lib/lockfile/helpers/generate-bun-lockfile.ts

@@ -211,7 +211,11 @@ export async function generateBunLockfile({
     const internalDepWorkspaceKeys = new Map<string, string>();
     for (const name of internalDepPackageNames) {
       const pkg = got(packagesRegistry, name);
-      internalDepWorkspaceKeys.set(name, pkg.rootRelativeDir);
+      /** Normalize to POSIX separators for matching bun.lock workspace keys */
+      const workspaceKey = pkg.rootRelativeDir
+        .split(path.sep)
+        .join(path.posix.sep);
+      internalDepWorkspaceKeys.set(name, workspaceKey);
     }
 
     /** Build the filtered workspaces object */
@@ -219,7 +223,13 @@ export async function generateBunLockfile({
 
     /** Remap the target workspace to root ("") */
     const targetEntry = lockfile.workspaces[targetWorkspaceKey];
-    if (targetEntry) {
+    if (!targetEntry) {
+      throw new Error(
+        `Target workspace "${targetWorkspaceKey}" not found in bun.lock. Available workspaces: ${Object.keys(lockfile.workspaces).join(", ")}`,
+      );
+    }
+
+    {
       const entry = { ...targetEntry };
       if (!includeDevDependencies) {
         delete entry.devDependencies;
@@ -330,7 +340,11 @@ export async function generateBunLockfile({
     }
 
     const outputPath = path.join(isolateDir, "bun.lock");
-    await fs.writeFile(outputPath, serializeWithTrailingCommas(outputLockfile));
+    /** Append trailing newline to match Bun's native output format */
+    await fs.writeFile(
+      outputPath,
+      serializeWithTrailingCommas(outputLockfile) + "\n",
+    );
 
     log.debug("Created lockfile at", outputPath);
   } catch (err) {

package/src/lib/manifest/adapt-target-package-manifest.ts

@@ -56,7 +56,8 @@ export async function adaptTargetPackageManifest({
       ? /**
          * For PNPM and Bun the output itself is a workspace so we can preserve
          * the specifiers with "workspace:*" in the output manifest, but we do
-         * want to adopt the pnpm.overrides field from the root package.json.
+         * want to adopt workspace-level fields from the root package.json
+         * (pnpm.overrides for PNPM, top-level overrides for Bun).
          */
         await adoptPnpmFieldsFromRoot(
           manifestWithResolvedCatalogs,

package/src/lib/manifest/helpers/adapt-internal-package-manifests.test.ts

@@ -0,0 +1,181 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import type { PackageManifest, PackagesRegistry } from "~/lib/types";
+
+/** Mock dependencies */
+vi.mock("~/lib/package-manager", () => ({
+  usePackageManager: vi.fn(),
+}));
+
+vi.mock("../io", () => ({
+  writeManifest: vi.fn(),
+}));
+
+vi.mock("./adapt-manifest-internal-deps", () => ({
+  adaptManifestInternalDeps: vi.fn(({ manifest }) => manifest),
+}));
+
+vi.mock("./resolve-catalog-dependencies", () => ({
+  resolveCatalogDependencies: vi.fn((deps) => Promise.resolve(deps)),
+}));
+
+const { usePackageManager } = vi.mocked(await import("~/lib/package-manager"));
+
+const { writeManifest } = vi.mocked(await import("../io"));
+
+const { adaptInternalPackageManifests } =
+  await import("./adapt-internal-package-manifests");
+
+describe("adaptInternalPackageManifests", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    usePackageManager.mockReturnValue({
+      name: "pnpm",
+      version: "9.0.0",
+      majorVersion: 9,
+    });
+  });
+
+  function createRegistry(
+    entries: Record<
+      string,
+      { rootRelativeDir: string; manifest: PackageManifest }
+    >,
+  ): PackagesRegistry {
+    const registry: PackagesRegistry = {};
+    for (const [name, { rootRelativeDir, manifest }] of Object.entries(
+      entries,
+    )) {
+      registry[name] = {
+        absoluteDir: `/workspace/${rootRelativeDir}`,
+        rootRelativeDir,
+        manifest,
+      };
+    }
+    return registry;
+  }
+
+  it("should preserve scripts in internal dependency manifests", async () => {
+    const manifest: PackageManifest = {
+      name: "@repo/database",
+      version: "1.0.0",
+      scripts: {
+        postinstall: "prisma generate",
+        build: "tsc",
+      },
+      dependencies: {
+        prisma: "^5.0.0",
+      },
+      devDependencies: {
+        typescript: "^5.0.0",
+      },
+    };
+
+    const packagesRegistry = createRegistry({
+      "@repo/database": {
+        rootRelativeDir: "packages/database",
+        manifest,
+      },
+    });
+
+    await adaptInternalPackageManifests({
+      internalPackageNames: ["@repo/database"],
+      packagesRegistry,
+      isolateDir: "/output",
+      forceNpm: false,
+      workspaceRootDir: "/workspace",
+    });
+
+    expect(writeManifest).toHaveBeenCalledOnce();
+
+    const writtenManifest = writeManifest.mock.calls[0]![1];
+
+    expect(writtenManifest.scripts).toEqual({
+      postinstall: "prisma generate",
+      build: "tsc",
+    });
+  });
+
+  it("should strip the prepare script from internal dependency manifests", async () => {
+    const manifest: PackageManifest = {
+      name: "@repo/common",
+      version: "1.0.0",
+      scripts: {
+        prepare: "npm run clean && npm run build",
+        clean: "del-cli dist",
+        build: "tsdown",
+        postinstall: "prisma generate",
+      },
+      dependencies: {
+        ky: "^1.0.0",
+      },
+      devDependencies: {
+        "del-cli": "^7.0.0",
+        tsdown: "^0.20.0",
+      },
+    };
+
+    const packagesRegistry = createRegistry({
+      "@repo/common": {
+        rootRelativeDir: "packages/common",
+        manifest,
+      },
+    });
+
+    await adaptInternalPackageManifests({
+      internalPackageNames: ["@repo/common"],
+      packagesRegistry,
+      isolateDir: "/output",
+      forceNpm: false,
+      workspaceRootDir: "/workspace",
+    });
+
+    expect(writeManifest).toHaveBeenCalledOnce();
+
+    const writtenManifest = writeManifest.mock.calls[0]![1];
+
+    /** prepare should be stripped because it depends on devDependency binaries */
+    expect(writtenManifest.scripts?.prepare).toBeUndefined();
+
+    /** Other scripts should be preserved */
+    expect(writtenManifest.scripts).toEqual({
+      clean: "del-cli dist",
+      build: "tsdown",
+      postinstall: "prisma generate",
+    });
+  });
+
+  it("should strip devDependencies from internal dependency manifests", async () => {
+    const manifest: PackageManifest = {
+      name: "@repo/shared",
+      version: "1.0.0",
+      dependencies: {
+        lodash: "^4.0.0",
+      },
+      devDependencies: {
+        vitest: "^1.0.0",
+        typescript: "^5.0.0",
+      },
+    };
+
+    const packagesRegistry = createRegistry({
+      "@repo/shared": {
+        rootRelativeDir: "packages/shared",
+        manifest,
+      },
+    });
+
+    await adaptInternalPackageManifests({
+      internalPackageNames: ["@repo/shared"],
+      packagesRegistry,
+      isolateDir: "/output",
+      forceNpm: false,
+      workspaceRootDir: "/workspace",
+    });
+
+    expect(writeManifest).toHaveBeenCalledOnce();
+
+    const writtenManifest = writeManifest.mock.calls[0]![1];
+
+    expect(writtenManifest.devDependencies).toBeUndefined();
+  });
+});

package/src/lib/manifest/helpers/adapt-internal-package-manifests.ts

@@ -31,8 +31,19 @@ export async function adaptInternalPackageManifests({
     internalPackageNames.map(async (packageName) => {
       const { manifest, rootRelativeDir } = got(packagesRegistry, packageName);
 
-      /** Dev dependencies and scripts are never included for internal deps */
-      const strippedManifest = omit(manifest, ["scripts", "devDependencies"]);
+      /** Dev dependencies are never included for internal deps */
+      const strippedManifest = omit(manifest, ["devDependencies"]);
+
+      /**
+       * Strip the `prepare` script because it runs during `pnpm install` and
+       * typically depends on devDependency binaries (e.g. tsdown, del-cli)
+       * which are not available in the isolated output. Other lifecycle
+       * scripts like `postinstall` are preserved because they handle runtime
+       * setup (e.g. Prisma client generation).
+       */
+      if (strippedManifest.scripts) {
+        strippedManifest.scripts = omit(strippedManifest.scripts, ["prepare"]);
+      }
 
       /** Resolve catalog dependencies before adapting internal deps */
       const manifestWithResolvedCatalogs = {
@@ -44,10 +55,11 @@ export async function adaptInternalPackageManifests({
       };
 
       const outputManifest =
-        packageManager.name === "pnpm" && !forceNpm
+        (packageManager.name === "pnpm" || packageManager.name === "bun") &&
+        !forceNpm
           ? /**
-             * For PNPM the output itself is a workspace so we can preserve the specifiers
-             * with "workspace:*" in the output manifest.
+             * For PNPM and Bun the output itself is a workspace so we can preserve
+             * the specifiers with "workspace:*" in the output manifest.
              */
             manifestWithResolvedCatalogs
           : /** For other package managers we replace the links to internal dependencies */

package/src/lib/manifest/helpers/adopt-pnpm-fields-from-root.test.ts

@@ -12,10 +12,16 @@ vi.mock("~/lib/utils", () => ({
   readTypedJson: vi.fn(),
 }));
 
+vi.mock("~/lib/package-manager", () => ({
+  usePackageManager: vi.fn(() => ({ name: "pnpm", majorVersion: 9 })),
+}));
+
 const { isRushWorkspace, readTypedJson } = vi.mocked(
   await import("~/lib/utils"),
 );
 
+const { usePackageManager } = vi.mocked(await import("~/lib/package-manager"));
+
 describe("adoptPnpmFieldsFromRoot", () => {
   beforeEach(() => {
     vi.clearAllMocks();
@@ -209,4 +215,59 @@ describe("adoptPnpmFieldsFromRoot", () => {
       },
     });
   });
+
+  it("should adopt top-level overrides for Bun", async () => {
+    usePackageManager.mockReturnValue({
+      name: "bun",
+      majorVersion: 1,
+      version: "1.0.0",
+      packageManagerString: "bun@1.0.0",
+    } as ReturnType<typeof usePackageManager>);
+    isRushWorkspace.mockReturnValue(false);
+    readTypedJson.mockResolvedValue({
+      name: "root",
+      version: "1.0.0",
+      overrides: {
+        foo: "^1.0.0",
+      },
+    } as unknown as ProjectManifest);
+
+    const targetManifest: PackageManifest = {
+      name: "test-package",
+      version: "1.0.0",
+    };
+
+    const result = await adoptPnpmFieldsFromRoot(targetManifest, "/workspace");
+
+    expect(result).toEqual({
+      name: "test-package",
+      version: "1.0.0",
+      overrides: {
+        foo: "^1.0.0",
+      },
+    });
+  });
+
+  it("should return original manifest for Bun when no overrides are present", async () => {
+    usePackageManager.mockReturnValue({
+      name: "bun",
+      majorVersion: 1,
+      version: "1.0.0",
+      packageManagerString: "bun@1.0.0",
+    } as ReturnType<typeof usePackageManager>);
+    isRushWorkspace.mockReturnValue(false);
+    readTypedJson.mockResolvedValue({
+      name: "root",
+      version: "1.0.0",
+    } as ProjectManifest);
+
+    const targetManifest: PackageManifest = {
+      name: "test-package",
+      version: "1.0.0",
+    };
+
+    const result = await adoptPnpmFieldsFromRoot(targetManifest, "/workspace");
+
+    expect(result).toEqual(targetManifest);
+  });
 });

package/src/lib/manifest/helpers/adopt-pnpm-fields-from-root.ts

@@ -1,12 +1,13 @@
 import type { ProjectManifest, PnpmSettings } from "@pnpm/types";
 import path from "path";
+import { usePackageManager } from "~/lib/package-manager";
 import type { PackageManifest } from "~/lib/types";
 import { isRushWorkspace, readTypedJson } from "~/lib/utils";
 
 /**
- * Adopts the `pnpm` fields from the root package manifest. Currently it takes
- * overrides, onlyBuiltDependencies, and ignoredBuiltDependencies, because these
- * are typically workspace-level configuration settings.
+ * Adopts workspace-level fields from the root package manifest. For pnpm this
+ * reads overrides, onlyBuiltDependencies, and ignoredBuiltDependencies from the
+ * `pnpm` key. For Bun it reads `overrides` from the top level.
  */
 export async function adoptPnpmFieldsFromRoot(
   targetPackageManifest: PackageManifest,
@@ -20,6 +21,44 @@ export async function adoptPnpmFieldsFromRoot(
     path.join(workspaceRootDir, "package.json"),
   );
 
+  const packageManager = usePackageManager();
+
+  if (packageManager.name === "bun") {
+    return adoptBunFieldsFromRoot(targetPackageManifest, rootPackageManifest);
+  }
+
+  return adoptPnpmFieldsOnly(targetPackageManifest, rootPackageManifest);
+}
+
+/** Adopt Bun's top-level overrides from the root manifest */
+function adoptBunFieldsFromRoot(
+  targetPackageManifest: PackageManifest,
+  rootPackageManifest: ProjectManifest,
+): PackageManifest {
+  /**
+   * Bun supports `overrides` at the top level of package.json (same as npm).
+   * Read from the root manifest and set them on the output manifest so that
+   * `bun install --frozen-lockfile` succeeds.
+   */
+  const overrides = (rootPackageManifest as Record<string, unknown>)[
+    "overrides"
+  ] as Record<string, string> | undefined;
+
+  if (!overrides) {
+    return targetPackageManifest;
+  }
+
+  return {
+    ...targetPackageManifest,
+    overrides,
+  } as PackageManifest;
+}
+
+/** Adopt pnpm-specific fields from the root manifest */
+function adoptPnpmFieldsOnly(
+  targetPackageManifest: PackageManifest,
+  rootPackageManifest: ProjectManifest,
+): PackageManifest {
   const { overrides, onlyBuiltDependencies, ignoredBuiltDependencies } =
     rootPackageManifest.pnpm || {};
 

package/src/lib/manifest/validate-manifest.test.ts

@@ -43,7 +43,7 @@ describe("validateManifestMandatoryFields", () => {
 
     expect(() =>
       validateManifestMandatoryFields(invalidDevManifest, packagePath, false),
-    ).toThrow(/missing mandatory fields: version/);
+    ).toThrow(/missing the "version" field/);
   });
 
   it("should throw error when version field is missing", () => {
@@ -54,7 +54,7 @@ describe("validateManifestMandatoryFields", () => {
 
     expect(() =>
       validateManifestMandatoryFields(invalidManifest, packagePath),
-    ).toThrow(/missing mandatory fields: version/);
+    ).toThrow(/missing the "version" field/);
   });
 
   it("should throw error when files field is missing", () => {
@@ -65,7 +65,7 @@ describe("validateManifestMandatoryFields", () => {
 
     expect(() =>
       validateManifestMandatoryFields(invalidManifest, packagePath),
-    ).toThrow(/missing mandatory fields: files/);
+    ).toThrow(/missing the "files" field/);
   });
 
   it("should throw error when files field is empty array", () => {
@@ -77,7 +77,7 @@ describe("validateManifestMandatoryFields", () => {
 
     expect(() =>
       validateManifestMandatoryFields(invalidManifest, packagePath),
-    ).toThrow(/missing mandatory fields: files/);
+    ).toThrow(/missing the "files" field/);
   });
 
   it("should throw error when files field is not an array", () => {
@@ -89,7 +89,7 @@ describe("validateManifestMandatoryFields", () => {
 
     expect(() =>
       validateManifestMandatoryFields(invalidManifest, packagePath),
-    ).toThrow(/missing mandatory fields: files/);
+    ).toThrow(/missing the "files" field/);
   });
 
   it("should throw error when both fields are missing", () => {
@@ -99,20 +99,29 @@ describe("validateManifestMandatoryFields", () => {
 
     expect(() =>
       validateManifestMandatoryFields(invalidManifest, packagePath),
-    ).toThrow(/missing mandatory fields: version, files/);
+    ).toThrow(/missing mandatory fields in its package\.json: version, files/);
   });
 
-  it("should include helpful error message", () => {
+  it("should include documentation URL in error message", () => {
     const invalidManifest = {
       name: "test-package",
     } as PackageManifest;
 
     expect(() =>
       validateManifestMandatoryFields(invalidManifest, packagePath),
-    ).toThrow(/missing mandatory fields: version, files/);
+    ).toThrow(
+      /See https:\/\/isolate-package\.codecompose\.dev\/getting-started#prerequisites/,
+    );
+
+    const singleFieldManifest = {
+      name: "test-package",
+      version: "1.0.0",
+    } as PackageManifest;
 
     expect(() =>
-      validateManifestMandatoryFields(invalidManifest, packagePath),
-    ).toThrow(/See the documentation for more details/);
+      validateManifestMandatoryFields(singleFieldManifest, packagePath),
+    ).toThrow(
+      /See https:\/\/isolate-package\.codecompose\.dev\/getting-started#define-files-field-in-each-package-manifest/,
+    );
   });
 });

package/src/lib/manifest/validate-manifest.ts

@@ -1,6 +1,14 @@
 import { useLogger } from "../logger";
 import type { PackageManifest } from "../types";
 
+/** Maps field names to their documentation URLs */
+const fieldDocUrls: Record<string, string> = {
+  version:
+    "https://isolate-package.codecompose.dev/getting-started#define-version-field-in-each-package-manifest",
+  files:
+    "https://isolate-package.codecompose.dev/getting-started#define-files-field-in-each-package-manifest",
+};
+
 /**
  * Validate that mandatory fields are present in the package manifest. These
  * fields are required for the isolate process to work properly.
@@ -38,7 +46,11 @@ export function validateManifestMandatoryFields(
   }
 
   if (missingFields.length > 0) {
-    const errorMessage = `Package at ${packagePath} is missing mandatory fields: ${missingFields.join(", ")}. See the documentation for more details.`;
+    const field = missingFields[0]!;
+    const errorMessage =
+      missingFields.length === 1
+        ? `Package at ${packagePath} is missing the "${field}" field in its package.json. See ${fieldDocUrls[field] ?? "https://isolate-package.codecompose.dev/getting-started#prerequisites"}`
+        : `Package at ${packagePath} is missing mandatory fields in its package.json: ${missingFields.join(", ")}. See https://isolate-package.codecompose.dev/getting-started#prerequisites`;
 
     log.error(errorMessage);
     throw new Error(errorMessage);