@mintlify/package-builder 0.0.0-stage → 0.0.3

package/dist/cli.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+import { readFileSync, realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { build } from './build.js';
+const USAGE = `Usage: mint-package-builder build --input <input.json> --out <dir> [--installer local|npm-ci|prepared] [--json]
+
+input.json holds a BuildInput (docsRoot, packages, islands, snippetFiles, installer, registryTokens,
+expected). With expected { depsHash, islandsHash } the manifest carries those hashes and the build
+fails if the builder computes different ones.
+--out overrides outDir; --installer overrides installer. Exits 1 when the build has errors.`;
+export function parseArgs(argv) {
+    const args = { json: false };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--input')
+            args.input = argv[++i];
+        else if (arg === '--out')
+            args.out = argv[++i];
+        else if (arg === '--installer')
+            args.installer = argv[++i];
+        else if (arg === '--json')
+            args.json = true;
+        else if (!args.command && arg && !arg.startsWith('-'))
+            args.command = arg;
+        else
+            throw new Error(`Unknown argument: ${arg}`);
+    }
+    return args;
+}
+function readExpected(value) {
+    const record = typeof value === 'object' && value !== null ? value : {};
+    const text = (field) => (typeof field === 'string' ? field : '');
+    return { depsHash: text(record.depsHash), islandsHash: text(record.islandsHash) };
+}
+function kb(bytes) {
+    return `${(bytes / 1024).toFixed(1)} KB`;
+}
+export function formatResult(result) {
+    const { manifest, stats } = result;
+    const lines = [
+        `Build ${manifest.buildId} ${result.ok ? 'succeeded' : 'failed'}`,
+        `react ${manifest.react.version || '?'} / react-dom ${manifest.react.domVersion || '?'}`,
+        `install ${Math.round(stats.installMs)} ms, bundle ${Math.round(stats.bundleMs)} ms, render ${Math.round(stats.renderMs)} ms`,
+        `client ${kb(stats.clientBytes)} (${kb(stats.clientGzipBytes)} gzip), server ${kb(stats.serverBytes)}`,
+    ];
+    for (const [name, { version }] of Object.entries(manifest.packages))
+        lines.push(`  ${name}@${version}`);
+    for (const [id, island] of Object.entries(manifest.islands)) {
+        const gz = stats.islandClientGzipBytes[id];
+        lines.push(`  island ${id}: ${island.html !== undefined ? `ssr ${island.ssrMs ?? 0} ms` : 'client-only'}${gz !== undefined ? `, ${kb(gz)} gzip JS` : ''}`);
+    }
+    for (const d of manifest.diagnostics)
+        lines.push(`${d.level === 'error' ? 'error' : 'warn '} [${d.code}]${d.pkg ? ` ${d.pkg}:` : ''} ${d.message}`);
+    return lines.join('\n');
+}
+export async function main(argv) {
+    let args;
+    try {
+        args = parseArgs(argv);
+    }
+    catch (err) {
+        process.stderr.write(`${err.message}\n${USAGE}\n`);
+        return 2;
+    }
+    if (args.command !== 'build' || !args.input) {
+        process.stderr.write(`${USAGE}\n`);
+        return 2;
+    }
+    const raw = JSON.parse(readFileSync(resolve(args.input), 'utf8'));
+    const outDir = args.out ?? raw.outDir;
+    if (!outDir || !raw.docsRoot) {
+        process.stderr.write(`input.json needs docsRoot, and --out or outDir is required.\n${USAGE}\n`);
+        return 2;
+    }
+    const installer = args.installer ?? raw.installer ?? 'npm-ci';
+    if (installer !== 'local' && installer !== 'npm-ci' && installer !== 'prepared') {
+        process.stderr.write(`--installer must be local, npm-ci or prepared\n`);
+        return 2;
+    }
+    const result = await build({
+        docsRoot: resolve(raw.docsRoot),
+        packages: raw.packages ?? {},
+        islands: raw.islands ?? [],
+        snippetFiles: raw.snippetFiles ?? {},
+        outDir: resolve(outDir),
+        installer,
+        registryTokens: raw.registryTokens,
+        packageManagers: raw.packageManagers,
+        renderMemoryLimitBytes: raw.renderMemoryLimitBytes,
+        ...(raw.expected !== undefined ? { expected: readExpected(raw.expected) } : {}),
+    });
+    process.stderr.write(`${formatResult(result)}\n`);
+    if (args.json)
+        process.stdout.write(`${JSON.stringify(result)}\n`);
+    return result.ok ? 0 : 1;
+}
+function invokedDirectly() {
+    try {
+        return (process.argv[1] !== undefined &&
+            realpathSync(process.argv[1]) === fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+}
+if (invokedDirectly()) {
+    main(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
+        process.stderr.write(`${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`);
+        process.exit(1);
+    });
+}

package/dist/diagnostics.d.ts

@@ -0,0 +1,11 @@
+import type { BuildDiagnostic } from './types.js';
+export declare class Diagnostics {
+    readonly list: BuildDiagnostic[];
+    private readonly seen;
+    add(diagnostic: BuildDiagnostic): void;
+    error(code: string, message: string, pkg?: string): void;
+    warn(code: string, message: string, pkg?: string): void;
+    addAll(diagnostics: BuildDiagnostic[]): void;
+    hasErrors(): boolean;
+}
+export declare function hasErrors(diagnostics: BuildDiagnostic[]): boolean;

package/dist/diagnostics.js

@@ -0,0 +1,32 @@
+export class Diagnostics {
+    constructor() {
+        this.list = [];
+        this.seen = new Set();
+    }
+    add(diagnostic) {
+        const key = `${diagnostic.level}|${diagnostic.code}|${diagnostic.pkg ?? ''}|${diagnostic.message}`;
+        if (this.seen.has(key))
+            return;
+        this.seen.add(key);
+        this.list.push(diagnostic);
+    }
+    error(code, message, pkg) {
+        this.add(withPkg({ level: 'error', code, message }, pkg));
+    }
+    warn(code, message, pkg) {
+        this.add(withPkg({ level: 'warning', code, message }, pkg));
+    }
+    addAll(diagnostics) {
+        for (const d of diagnostics)
+            this.add(d);
+    }
+    hasErrors() {
+        return this.list.some((d) => d.level === 'error');
+    }
+}
+function withPkg(d, pkg) {
+    return pkg === undefined ? d : { ...d, pkg };
+}
+export function hasErrors(diagnostics) {
+    return diagnostics.some((d) => d.level === 'error');
+}

package/dist/hashing.d.ts

@@ -0,0 +1,28 @@
+import type { IslandSpec } from './types.js';
+export declare const DEPS_HASH_ALGORITHM = "mint-pkg-deps/1";
+export declare const ISLANDS_HASH_ALGORITHM = "mint-pkg-islands/1";
+export type HashLockfileKind = 'npm' | 'pnpm';
+export type DepsHashInput = {
+    lockfileBytes: Uint8Array | string;
+    lockfileKind: HashLockfileKind;
+    dependencies: Record<string, string>;
+    registries?: Record<string, string>;
+    builderVersion: string;
+};
+export type IslandsHashInput = {
+    islands: Pick<IslandSpec, 'id' | 'kind' | 'module'>[];
+    snippetFiles: Record<string, string | Uint8Array>;
+    provider?: string;
+    css?: string[];
+    ssr?: boolean;
+    isolation?: 'page' | 'frame';
+};
+export declare function sha256Hex(data: string | Uint8Array): string;
+export declare function sha384Integrity(data: Uint8Array | string): string;
+export declare function gzipSize(data: Uint8Array | string): number;
+export declare function stableStringify(value: unknown): string;
+export declare function computeDepsHash(input: DepsHashInput): string;
+export declare function computeIslandsHash(input: IslandsHashInput): string;
+export declare function computeBuildId(depsHash: string, islandsHash: string): string;
+export declare function islandIdFor(moduleSource: string): string;
+export declare function islandPrefix(id: string): string;

package/dist/hashing.js

@@ -0,0 +1,98 @@
+import { createHash } from 'node:crypto';
+import { gzipSync } from 'node:zlib';
+/*
+ * Build hashes: the one canonical definition.
+ *
+ * The server (S1, api/utils/packages/packageBuildHashes.ts) and the package-builder worker (S2,
+ * src/hashes.ts) carry ports of these functions. All three must produce the same output for the
+ * vectors in __test__/fixtures/hash-vectors.json; that file is copied byte for byte into both
+ * repos. Change the algorithm only by bumping the `algorithm` tag and every copy together.
+ *
+ * Definitions:
+ *   H(bytes)        lowercase hex SHA-256. A string is hashed as its UTF-8 bytes.
+ *   canonical(v)    JSON with no whitespace. Object keys are sorted by UTF-16 code unit order
+ *                   (JavaScript `<` on strings) and keys whose value is `undefined` are dropped.
+ *                   Arrays keep their order. Strings and numbers use JSON.stringify.
+ *
+ *   depsHash    = H(canonical({
+ *                   algorithm: 'mint-pkg-deps/1',
+ *                   builderVersion,                 // @mintlify/package-builder version
+ *                   lockfileKind,                   // 'npm' | 'pnpm'
+ *                   lockfile: H(lockfileBytes),     // the lockfile exactly as installed
+ *                   dependencies,                   // package.json "dependencies", {} when absent
+ *                   registries,                     // docs.json packages.registries as written, {} when absent
+ *                 }))
+ *
+ *   islandsHash = H(canonical({
+ *                   algorithm: 'mint-pkg-islands/1',
+ *                   islands: [{ id, kind, module: H(module) }] sorted by id,
+ *                   snippets: { [path]: H(source) },
+ *                   provider: provider ?? null,
+ *                   css: css ?? [],
+ *                   ssr: ssr ?? true,
+ *                   isolation: isolation ?? 'page',
+ *                 }))
+ *
+ *   buildId     = H(depsHash + islandsHash).slice(0, 32)
+ *
+ * Island `pagePath` and `imports` are left out on purpose: neither changes the build output, and
+ * leaving them out lets a build be reused when an unchanged island moves to another page.
+ */
+export const DEPS_HASH_ALGORITHM = 'mint-pkg-deps/1';
+export const ISLANDS_HASH_ALGORITHM = 'mint-pkg-islands/1';
+export function sha256Hex(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+export function sha384Integrity(data) {
+    return `sha384-${createHash('sha384').update(data).digest('base64')}`;
+}
+export function gzipSize(data) {
+    return gzipSync(data, { level: 9 }).length;
+}
+const byCodeUnit = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+export function stableStringify(value) {
+    if (value === undefined)
+        return 'null';
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(',')}]`;
+    const entries = Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => byCodeUnit(a, b));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(',')}}`;
+}
+export function computeDepsHash(input) {
+    return sha256Hex(stableStringify({
+        algorithm: DEPS_HASH_ALGORITHM,
+        builderVersion: input.builderVersion,
+        lockfileKind: input.lockfileKind,
+        lockfile: sha256Hex(input.lockfileBytes),
+        dependencies: input.dependencies,
+        registries: input.registries ?? {},
+    }));
+}
+export function computeIslandsHash(input) {
+    const islands = input.islands
+        .map((island) => ({ id: island.id, kind: island.kind, module: sha256Hex(island.module) }))
+        .sort((a, b) => byCodeUnit(a.id, b.id));
+    const snippets = Object.fromEntries(Object.entries(input.snippetFiles).map(([path, source]) => [path, sha256Hex(source)]));
+    return sha256Hex(stableStringify({
+        algorithm: ISLANDS_HASH_ALGORITHM,
+        islands,
+        snippets,
+        provider: input.provider ?? null,
+        css: input.css ?? [],
+        ssr: input.ssr ?? true,
+        isolation: input.isolation ?? 'page',
+    }));
+}
+export function computeBuildId(depsHash, islandsHash) {
+    return sha256Hex(depsHash + islandsHash).slice(0, 32);
+}
+export function islandIdFor(moduleSource) {
+    return `i${sha256Hex(moduleSource).slice(0, 16)}`;
+}
+export function islandPrefix(id) {
+    return `mi-${id}-`;
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { build, MAX_CLIENT_GZIP_BYTES, MAX_SERVER_BUNDLE_BYTES } from './build.js';
+export { bundle, ISLAND_ID, ISLANDS_HOOKS_SPECIFIER, type BundleOptions, type BundleResult, } from './bundle.js';
+export { computeBuildId, computeDepsHash, computeIslandsHash, DEPS_HASH_ALGORITHM, ISLANDS_HASH_ALGORITHM, islandIdFor, islandPrefix, sha256Hex, sha384Integrity, stableStringify, type DepsHashInput, type HashLockfileKind, type IslandsHashInput, } from './hashing.js';
+export { generateNpmrc, install, type InstallOptions, type InstallResult } from './install.js';
+export { collectLocalFiles, type LocalFiles, type LocalFilesInput } from './local-files.js';
+export { findLockfile, LOCKFILE_NAMES, registryFor, validateLockfile, type FoundLockfile, type LockfileName, type LockfileValidation, } from './lockfile.js';
+export { checkDuplicateReact, checkPeerRanges, checkReactVersions, packageOfPath, readReactInfo, scanRemovedApis, singleReactPlugin, type ReactInfo, } from './react.js';
+export { ISLAND_RENDER_TIMEOUT_MS, renderIslands, type RenderOutcome } from './render.js';
+export { MAX_ISLAND_HTML_BYTES, sanitizeHtml, sanitizeIslandHtml } from './sanitize.js';
+export { satisfies } from './semver.js';
+export { BUILDER_VERSION } from './version.js';
+export type * from './types.js';

package/dist/index.js

@@ -0,0 +1,11 @@
+export { build, MAX_CLIENT_GZIP_BYTES, MAX_SERVER_BUNDLE_BYTES } from './build.js';
+export { bundle, ISLAND_ID, ISLANDS_HOOKS_SPECIFIER, } from './bundle.js';
+export { computeBuildId, computeDepsHash, computeIslandsHash, DEPS_HASH_ALGORITHM, ISLANDS_HASH_ALGORITHM, islandIdFor, islandPrefix, sha256Hex, sha384Integrity, stableStringify, } from './hashing.js';
+export { generateNpmrc, install } from './install.js';
+export { collectLocalFiles } from './local-files.js';
+export { findLockfile, LOCKFILE_NAMES, registryFor, validateLockfile, } from './lockfile.js';
+export { checkDuplicateReact, checkPeerRanges, checkReactVersions, packageOfPath, readReactInfo, scanRemovedApis, singleReactPlugin, } from './react.js';
+export { ISLAND_RENDER_TIMEOUT_MS, renderIslands } from './render.js';
+export { MAX_ISLAND_HTML_BYTES, sanitizeHtml, sanitizeIslandHtml } from './sanitize.js';
+export { satisfies } from './semver.js';
+export { BUILDER_VERSION } from './version.js';

package/dist/install.d.ts

@@ -0,0 +1,34 @@
+import { type FoundLockfile } from './lockfile.js';
+import { type PackageJson } from './package-json.js';
+import { type PackageManagerCommand, type SpawnHost } from './package-manager.js';
+import type { BuildDiagnostic, Installer, PackageManagerBinaries } from './types.js';
+export declare const INSTALL_TIMEOUT_MS: number;
+export type InstallResult = {
+    ok: boolean;
+    installRoot: string;
+    durationMs: number;
+    usedLegacyPeerDeps: boolean;
+    diagnostics: BuildDiagnostic[];
+    cleanup(): Promise<void>;
+};
+export type InstallOptions = {
+    docsRoot: string;
+    installer: Installer;
+    lockfile?: FoundLockfile;
+    packageJson?: PackageJson;
+    registries?: Record<string, string>;
+    registryTokens?: Record<string, string>;
+    packageManagers?: PackageManagerBinaries;
+    expectedVersions?: Record<string, string>;
+    timeoutMs?: number;
+    host?: SpawnHost;
+};
+export declare function pnpmCommand(packageJson: PackageJson, binaries: Record<string, string> | undefined, host: SpawnHost | undefined): {
+    command: PackageManagerCommand;
+    diagnostic?: BuildDiagnostic;
+};
+export declare function generateNpmrc(registries: Record<string, string> | undefined, tokens: Record<string, string> | undefined): {
+    npmrc: string;
+    diagnostics: BuildDiagnostic[];
+};
+export declare function install(opts: InstallOptions): Promise<InstallResult>;

package/dist/install.js

@@ -0,0 +1,325 @@
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdtemp, realpath, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { lockfileKind, NPMRC_COMMENT_OR_ESCAPE, NPMRC_COMMENT_OR_ESCAPE_PROBLEM, registryProblem, } from './lockfile.js';
+import { cleanPackageJson } from './package-json.js';
+import { resolvePackageManager, } from './package-manager.js';
+export const INSTALL_TIMEOUT_MS = 10 * 60 * 1000;
+const PASSTHROUGH_ENV = [
+    'PATH',
+    'HOME',
+    'USERPROFILE',
+    'APPDATA',
+    'LOCALAPPDATA',
+    'TMPDIR',
+    'TMP',
+    'TEMP',
+    'LANG',
+    'SystemRoot',
+    'HTTPS_PROXY',
+    'HTTP_PROXY',
+    'NO_PROXY',
+    'https_proxy',
+    'http_proxy',
+    'no_proxy',
+    'NODE_EXTRA_CA_CERTS',
+    'SSL_CERT_FILE',
+    'npm_config_cache',
+    'NPM_CONFIG_CACHE',
+];
+function runCommand(cmd, args, cwd, env, timeoutMs) {
+    return new Promise((resolvePromise) => {
+        const child = spawn(cmd, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
+        let output = '';
+        const append = (chunk) => {
+            output = (output + chunk.toString()).slice(-64_000);
+        };
+        child.stdout.on('data', append);
+        child.stderr.on('data', append);
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGKILL');
+        }, timeoutMs);
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            resolvePromise({ code: -1, output: `${output}\n${err.message}`, timedOut });
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            resolvePromise({ code, output, timedOut });
+        });
+    });
+}
+function registryHostAndPath(url) {
+    const u = new URL(url);
+    const path = u.pathname.endsWith('/') ? u.pathname : `${u.pathname}/`;
+    return `${u.host}${path}`;
+}
+function tokenRegistry(url) {
+    try {
+        if (new URL(url).protocol !== 'https:')
+            return undefined;
+        return registryHostAndPath(url);
+    }
+    catch {
+        return undefined;
+    }
+}
+const PNPM_VERSION = /^pnpm@(\d+)\./;
+export function pnpmCommand(packageJson, binaries, host) {
+    const fallback = resolvePackageManager('pnpm', host);
+    if (!binaries || Object.keys(binaries).length === 0)
+        return { command: fallback };
+    const requested = typeof packageJson.packageManager === 'string' ? packageJson.packageManager : undefined;
+    const major = requested ? PNPM_VERSION.exec(requested)?.[1] : undefined;
+    const path = major ? binaries[major] : undefined;
+    if (path) {
+        return {
+            command: /\.[cm]?js$/.test(path)
+                ? { ok: true, command: process.execPath, args: [path] }
+                : { ok: true, command: path, args: [] },
+        };
+    }
+    if (!requested)
+        return { command: fallback };
+    const supported = Object.keys(binaries)
+        .sort((a, b) => Number(a) - Number(b))
+        .join(', ');
+    return {
+        command: fallback,
+        diagnostic: {
+            level: 'warning',
+            code: 'package-manager-version-unsupported',
+            message: `package.json asks for ${requested}; builds use pnpm ${supported}, so the default pnpm was used.`,
+        },
+    };
+}
+const INVALID_HEADER_VALUE = /[^\t\x20-\x7e\x80-\xff]/;
+const NPMRC_STRIPPED_EDGE = /^[\s"']|[\s"']$/;
+function registryTokenProblem(token) {
+    if (/[\r\n]/.test(token))
+        return 'a newline';
+    if (INVALID_HEADER_VALUE.test(token))
+        return 'a character HTTP headers cannot carry';
+    if (token.includes('${'))
+        return '${, which npm expands from environment variables';
+    if (NPMRC_STRIPPED_EDGE.test(token)) {
+        return 'quotes or whitespace at either end, which npm strips and unescapes in .npmrc';
+    }
+    if (NPMRC_COMMENT_OR_ESCAPE.test(token))
+        return NPMRC_COMMENT_OR_ESCAPE_PROBLEM;
+    return undefined;
+}
+export function generateNpmrc(registries, tokens) {
+    const diagnostics = [];
+    const lines = [
+        'registry=https://registry.npmjs.org/',
+        'ignore-scripts=true',
+        'audit=false',
+        'fund=false',
+        'update-notifier=false',
+    ];
+    const valid = {};
+    for (const [scope, url] of Object.entries(registries ?? {}).sort()) {
+        const problem = registryProblem(scope, url);
+        if (problem) {
+            diagnostics.push({ level: 'error', code: 'registry-invalid', message: problem });
+            continue;
+        }
+        valid[scope] = registryHostAndPath(url);
+        lines.push(`${scope}:registry=https://${valid[scope]}`);
+    }
+    const scopesByRegistry = new Map();
+    for (const [scope, hostAndPath] of Object.entries(valid)) {
+        scopesByRegistry.set(hostAndPath, [...(scopesByRegistry.get(hostAndPath) ?? []), scope]);
+    }
+    for (const [registry, token] of Object.entries(tokens ?? {}).sort()) {
+        const hostAndPath = tokenRegistry(registry);
+        const scopes = hostAndPath === undefined ? undefined : scopesByRegistry.get(hostAndPath);
+        if (!scopes) {
+            if (Object.values(registries ?? {}).includes(registry))
+                continue;
+            diagnostics.push({
+                level: 'warning',
+                code: 'registry-token-unused',
+                message: `A registry token was provided for ${registry}, but no scope in packages.registries uses that registry, so it was not sent.`,
+            });
+            continue;
+        }
+        const problem = registryTokenProblem(token);
+        if (problem) {
+            diagnostics.push({
+                level: 'error',
+                code: 'registry-token-invalid',
+                message: `The token for ${scopes.join(', ')} contains ${problem}.`,
+            });
+            continue;
+        }
+        lines.push(`//${hostAndPath}:_authToken=${token}`);
+    }
+    return { npmrc: `${lines.join('\n')}\n`, diagnostics };
+}
+function localDrift(installRoot, expected, level) {
+    const out = [];
+    for (const [name, version] of Object.entries(expected)) {
+        const pkgPath = join(installRoot, 'node_modules', name, 'package.json');
+        let installed;
+        try {
+            installed = JSON.parse(readFileSync(pkgPath, 'utf8')).version;
+        }
+        catch {
+            installed = undefined;
+        }
+        if (installed !== version) {
+            out.push({
+                level,
+                code: 'local-node-modules-drift',
+                message: `node_modules has ${name} ${installed ?? '(missing)'} but the lockfile has ${version}. Run npm install.`,
+                pkg: name,
+            });
+        }
+    }
+    return out;
+}
+async function installExisting(opts) {
+    const start = performance.now();
+    const installRoot = await realpath(opts.docsRoot);
+    const diagnostics = [];
+    const prepared = opts.installer === 'prepared';
+    if (!existsSync(join(installRoot, 'node_modules'))) {
+        diagnostics.push({
+            level: 'error',
+            code: 'install-missing-node-modules',
+            message: prepared
+                ? `No node_modules in ${installRoot}. Install packages before building.`
+                : `No node_modules in ${installRoot}. Run npm install there first.`,
+        });
+    }
+    else if (opts.expectedVersions) {
+        diagnostics.push(...localDrift(installRoot, opts.expectedVersions, prepared ? 'error' : 'warning'));
+    }
+    return {
+        ok: diagnostics.every((d) => d.level !== 'error'),
+        installRoot,
+        durationMs: performance.now() - start,
+        usedLegacyPeerDeps: false,
+        diagnostics,
+        cleanup: async () => { },
+    };
+}
+function failureTail(output) {
+    const lines = output
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l && !/^npm (warn|notice)/i.test(l));
+    return lines.slice(-12).join('\n');
+}
+async function installClean(opts) {
+    const start = performance.now();
+    const diagnostics = [];
+    const dir = await realpath(await mkdtemp(join(tmpdir(), 'mint-pkg-install-')));
+    const cleanup = () => rm(dir, { recursive: true, force: true });
+    const fail = (code, message) => {
+        diagnostics.push({ level: 'error', code, message });
+        return {
+            ok: false,
+            installRoot: dir,
+            durationMs: performance.now() - start,
+            usedLegacyPeerDeps: false,
+            diagnostics,
+            cleanup,
+        };
+    };
+    if (!opts.lockfile)
+        return fail('lockfile-missing', 'A lockfile is required for a clean install.');
+    if (!opts.packageJson)
+        return fail('package-json-missing', 'A package.json is required.');
+    await writeFile(join(dir, 'package.json'), cleanPackageJson(opts.packageJson));
+    await writeFile(join(dir, basename(opts.lockfile.path)), opts.lockfile.content);
+    const { npmrc, diagnostics: npmrcDiagnostics } = generateNpmrc(opts.registries, opts.registryTokens);
+    diagnostics.push(...npmrcDiagnostics);
+    if (npmrcDiagnostics.some((d) => d.level === 'error')) {
+        return {
+            ok: false,
+            installRoot: dir,
+            durationMs: performance.now() - start,
+            usedLegacyPeerDeps: false,
+            diagnostics,
+            cleanup,
+        };
+    }
+    const kind = lockfileKind(opts.lockfile.fileName);
+    const pm = kind === 'npm' ? 'npm' : 'pnpm';
+    let resolved;
+    if (kind === 'npm') {
+        resolved = resolvePackageManager('npm', opts.host);
+    }
+    else {
+        const chosen = pnpmCommand(opts.packageJson, opts.packageManagers?.pnpm, opts.host);
+        resolved = chosen.command;
+        if (chosen.diagnostic)
+            diagnostics.push(chosen.diagnostic);
+    }
+    if (!resolved.ok)
+        return fail('package-manager-missing', resolved.message);
+    const npmrcPath = join(dir, '.npmrc');
+    await writeFile(npmrcPath, npmrc, { mode: 0o600 });
+    const env = {};
+    for (const key of PASSTHROUGH_ENV)
+        if (process.env[key] !== undefined)
+            env[key] = process.env[key];
+    env.npm_config_userconfig = join(dir, '.npmrc-user-empty');
+    env.npm_config_globalconfig = join(dir, '.npmrc-global-empty');
+    env.NODE_ENV = 'production';
+    env.COREPACK_ENABLE_STRICT = '0';
+    env.COREPACK_ENABLE_AUTO_PIN = '0';
+    env.npm_config_manage_package_manager_versions = 'false';
+    const timeoutMs = opts.timeoutMs ?? INSTALL_TIMEOUT_MS;
+    const baseArgs = kind === 'npm'
+        ? ['ci', '--ignore-scripts', '--omit=dev', '--no-audit', '--no-fund']
+        : [
+            'install',
+            '--frozen-lockfile',
+            '--ignore-scripts',
+            '--ignore-pnpmfile',
+            '--prod',
+            '--config.package-import-method=copy',
+        ];
+    const run = (args) => runCommand(resolved.command, [...resolved.args, ...args], dir, env, timeoutMs);
+    let usedLegacyPeerDeps = false;
+    let result = await run(baseArgs);
+    if (result.code !== 0 && kind === 'npm' && /ERESOLVE/.test(result.output)) {
+        usedLegacyPeerDeps = true;
+        diagnostics.push({
+            level: 'warning',
+            code: 'npm-legacy-peer-deps',
+            message: 'npm ci failed with ERESOLVE (a peer range excludes an installed version); retried with --legacy-peer-deps.',
+        });
+        result = await run([...baseArgs, '--legacy-peer-deps']);
+    }
+    await rm(npmrcPath, { force: true });
+    if (result.code !== 0) {
+        const reason = result.timedOut
+            ? `timed out after ${Math.round(timeoutMs / 1000)} s`
+            : `exited with code ${String(result.code)}`;
+        return {
+            ...fail('install-failed', `${pm} ${baseArgs[0]} ${reason}:\n${failureTail(result.output)}`),
+            usedLegacyPeerDeps,
+        };
+    }
+    return {
+        ok: true,
+        installRoot: dir,
+        durationMs: performance.now() - start,
+        usedLegacyPeerDeps,
+        diagnostics,
+        cleanup,
+    };
+}
+export function install(opts) {
+    return opts.installer === 'npm-ci' ? installClean(opts) : installExisting(opts);
+}