isolated-deps 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Cezar Augusto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+# optional-deps-lib
+
+> Deterministically install optional tooling dependencies into an isolated cache root instead of mutating the user's project.
+
+`optional-deps-lib` is a small runtime helper for library authors who need to bootstrap optional packages on demand while keeping those installs reproducible and separate from the consumer's app.
+
+## Why this exists
+
+- Keeps optional tooling installs outside the user's project directory.
+- Lets the client choose exact dependency specs and versions.
+- Verifies installed packages after each install attempt instead of trusting exit codes alone.
+- Recovers from partial installs by retrying and, if needed, recreating only the isolated cache root.
+
+## Installation
+
+```bash
+npm install optional-deps-lib
+```
+
+## How it works
+
+1. `optional-deps-lib` resolves an isolated cache directory for optional packages.
+2. It writes a small manifest with the exact specs requested by the client.
+3. It detects the active package manager (`npm`, `pnpm`, `yarn`, or `bun`).
+4. It installs the requested packages into the cache root.
+5. It re-checks resolution from the cache root before reporting success.
+
+The default cache root is versioned so installs remain deterministic across library upgrades.
+
+## Usage
+
+```js
+import {
+  installOptionalDependencies,
+  resolveOptionalInstallRoot,
+  hasDependency
+} from 'optional-deps-lib'
+
+async function ensurePostcss(projectPath) {
+  if (hasDependency(projectPath, 'postcss')) {
+    return null
+  }
+
+  const installed = await installOptionalDependencies('PostCSS', ['postcss@8.5.6'])
+
+  if (!installed) {
+    throw new Error('Failed to install PostCSS support')
+  }
+
+  return resolveOptionalInstallRoot()
+}
+```
+
+## Supported package managers
+
+- `npm`
+- `pnpm`
+- `yarn`
+- `bun`
+
+The installer also contains Windows and WSL-specific path handling so isolated installs can run in the same environment where the user launched the host tool.
+
+## Deterministic package versions
+
+This package does not ship its own dependency catalog.
+
+Clients are expected to pass exact dependency specs such as:
+
+- `postcss@8.5.6`
+- `react-refresh@0.18.0`
+- `@rspack/plugin-react-refresh@1.6.0`
+
+That keeps version policy with the consuming tool while this library focuses on isolated installation, package-manager execution, and verification.
+
+## API
+
+- `installOptionalDependencies(integration, dependencySpecs, options?)`
+- `installOptionalDependenciesBatch(plans)`
+- `resolveOptionalInstallRoot()`
+- `resolveDevelopInstallRoot()`
+- `hasDependency(projectPath, dependency)`
+
+### `installOptionalDependencies(integration, dependencySpecs, options?)`
+
+Installs the requested exact dependency specs into the isolated cache root and verifies they can be resolved afterward.
+
+### `installOptionalDependenciesBatch(plans)`
+
+Installs several integration plans in sequence and stops on the first failure.
+
+### `resolveOptionalInstallRoot()`
+
+Returns the versioned isolated cache directory used for optional installs.
+
+### `resolveDevelopInstallRoot()`
+
+Resolves the host `extension-develop` installation root when this package is used inside that runtime.
+
+### `hasDependency(projectPath, dependency)`
+
+Checks whether the nearest project `package.json` already declares the given dependency.
+
+## Guarantees
+
+- Optional installs are isolated from the consumer project.
+- User project lockfiles are not modified by bootstrap installs.
+- Install success is verified via follow-up resolution checks.
+- Recovery only resets the isolated optional dependency root.
+
+## License
+
+MIT (c) Cezar Augusto.

package/dist/cache-state.d.ts

@@ -0,0 +1,6 @@
+import { type OptionalDependencySpec } from './package-specs';
+export declare function prepareOptionalInstallState(input: {
+    installBaseDir: string;
+    dependencySpecs: OptionalDependencySpec[];
+    forceRecreateInstallRoot?: boolean;
+}): void;

package/dist/contract-types.d.ts

@@ -0,0 +1,18 @@
+export type OptionalDependencyVerificationRule = {
+    type: 'install-root';
+    packageId: string;
+} | {
+    type: 'module-context-resolve';
+    fromPackage: string;
+    packageId: string;
+} | {
+    type: 'module-context-load';
+    fromPackage: string;
+    packageId: string;
+};
+export type OptionalDependencyContract = {
+    id: string;
+    integration: string;
+    installPackages: string[];
+    verificationRules: OptionalDependencyVerificationRule[];
+};