@alex-dbs/coderuler 0.0.0-stage → 1.3.1

package/dist/adapter/filesystem/dependencies.js

@@ -0,0 +1,577 @@
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, mkdtemp, open, readFile, readdir, realpath, rm, writeFile } from 'node:fs/promises';
+import { Agent } from 'node:https';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { currentEnv } from 'npm-install-checks';
+import npa from 'npm-package-arg';
+import { parse as parseIntegrity } from 'ssri';
+import { prepareRuleDependencySdk, publishRuleDependencyInstallation, withRuleDependencyDirectoryLock } from './dependency-installation.js';
+const registry = 'https://registry.npmjs.org/';
+const lockName = 'coderuler.lock';
+const sdkName = '@alex-dbs/coderuler';
+const markerName = '.coderuler-install.json';
+const rootIdentity = { name: 'coderuler-rules', version: '1.0.0' };
+const forbiddenRootFields = ['scripts', 'workspaces', 'overrides', 'devDependencies', 'optionalDependencies', 'peerDependencies', 'peerDependenciesMeta'];
+const dependencyFields = ['dependencies', 'optionalDependencies', 'peerDependencies'];
+const compatibilityFields = ['engines', 'os', 'cpu', 'libc'];
+function code(error) {
+    return error !== null && typeof error === 'object' && 'code' in error ? String(error.code) : undefined;
+}
+function object(value, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error(`${label} must be an object`);
+    return value;
+}
+function packageName(name) {
+    const parsed = npa(name);
+    if (parsed.name !== name || !parsed.registry || parsed.rawSpec !== '*')
+        throw new Error(`Invalid dependency name ${JSON.stringify(name)}`);
+}
+function exactVersion(name, value) {
+    if (typeof value !== 'string')
+        throw new Error(`${name}: an exact package version is required`);
+    const spec = npa.resolve(name, value);
+    if (spec.type !== 'version' || spec.fetchSpec !== value)
+        throw new Error(`${name}: an exact package version is required`);
+    return value;
+}
+function hasBundledDependencies(value) {
+    return value !== undefined && value !== false && (!Array.isArray(value) || value.length > 0);
+}
+function dependencyMap(manifest, field, label) {
+    const value = manifest[field];
+    if (value === undefined)
+        return {};
+    const result = Object.create(null);
+    for (const [name, specifier] of Object.entries(object(value, `${label} ${field}`))) {
+        packageName(name);
+        if (typeof specifier !== 'string')
+            throw new Error(`${label}: invalid ${field} specification for ${name}`);
+        const parsed = npa.resolve(name, specifier);
+        if (!parsed.registry || !['version', 'range', 'tag'].includes(parsed.type)) {
+            throw new Error(`${label}: unsupported dependency source for ${name}; only public npm registry packages are supported`);
+        }
+        result[name] = specifier;
+    }
+    return result;
+}
+function locationName(location) {
+    const parts = location.split('/');
+    let name = '';
+    for (let index = 0; index < parts.length;) {
+        if (parts[index++] !== 'node_modules')
+            throw new Error(`Invalid lock package location ${JSON.stringify(location)}`);
+        const part = parts[index++];
+        if (!part)
+            throw new Error(`Invalid lock package location ${JSON.stringify(location)}`);
+        name = part.startsWith('@') ? `${part}/${parts[index++] ?? ''}` : part;
+        packageName(name);
+    }
+    if (!name || location.includes('\\'))
+        throw new Error(`Invalid lock package location ${JSON.stringify(location)}`);
+    return name;
+}
+function validateIntegrity(value, label) {
+    if (typeof value !== 'string')
+        throw new Error(`${label}: missing SHA-512 integrity`);
+    const parsed = parseIntegrity(value, { strict: true });
+    if (!parsed?.sha512?.length || parsed.sha512.some(hash => Buffer.from(hash.digest, 'base64').length !== 64)) {
+        throw new Error(`${label}: invalid SHA-512 integrity`);
+    }
+}
+function validateUrl(value, label) {
+    if (typeof value !== 'string')
+        throw new Error(`${label}: missing locked npm tarball URL`);
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`${label}: invalid locked npm tarball URL`);
+    }
+    if (url.origin !== 'https://registry.npmjs.org' || url.username || url.password || url.hash) {
+        throw new Error(`${label}: tarballs must use https://registry.npmjs.org without credentials or fragments`);
+    }
+}
+function validateLock(text, directory) {
+    let parsed;
+    try {
+        parsed = object(JSON.parse(text), 'Rule dependency lock');
+    }
+    catch (error) {
+        throw new Error('Invalid coderuler.lock JSON; regenerate it with coderuler deps add', { cause: error });
+    }
+    if (parsed.lockfileVersion !== 3)
+        throw new Error('coderuler.lock must use npm lockfileVersion 3');
+    const packages = object(parsed.packages, 'coderuler.lock packages');
+    const root = object(packages[''], 'coderuler.lock root package');
+    if (parsed.name !== rootIdentity.name || parsed.version !== rootIdentity.version || root.name !== rootIdentity.name || root.version !== rootIdentity.version) {
+        throw new Error('coderuler.lock must use the coderuler-rules@1.0.0 root identity');
+    }
+    for (const field of forbiddenRootFields) {
+        if (root[field] !== undefined || parsed[field] !== undefined)
+            throw new Error(`coderuler.lock root ${field} is not supported`);
+    }
+    for (const field of Object.keys(root)) {
+        if (!['name', 'version', 'dependencies'].includes(field))
+            throw new Error(`coderuler.lock root ${field} is not supported`);
+    }
+    const direct = dependencyMap(root, 'dependencies', 'coderuler.lock root');
+    for (const [name, version] of Object.entries(direct)) {
+        if (name === sdkName)
+            throw new Error(`${sdkName}: the SDK comes from the selected CodeRuler installation`);
+        exactVersion(name, version);
+    }
+    for (const [location, unknownEntry] of Object.entries(packages)) {
+        if (location === '')
+            continue;
+        const name = locationName(location);
+        const entry = object(unknownEntry, `coderuler.lock ${location}`);
+        exactVersion(name, entry.version);
+        if (entry.name !== undefined && entry.name !== name)
+            throw new Error(`${name}: package aliases are unsupported`);
+        for (const field of ['acceptDependencies', 'overrides', 'workspaces', 'packageExtensions', 'packageExtensionsHash', 'npmExtensionHash']) {
+            if (entry[field] !== undefined)
+                throw new Error(`${name}: unsupported graph metadata ${field}`);
+        }
+        if (entry.link || entry.inBundle || hasBundledDependencies(entry.bundleDependencies) || hasBundledDependencies(entry.bundledDependencies) || entry.hasShrinkwrap || entry.patched || entry.packageExtensionsApplied || entry.npmExtensionApplied) {
+            throw new Error(`${name}: linked, bundled and shrinkwrapped packages are unsupported`);
+        }
+        if (entry.hasInstallScript)
+            throw new Error(`${name}: install scripts are unsupported; choose a package without install-time build artifacts`);
+        validateIntegrity(entry.integrity, name);
+        validateUrl(entry.resolved, name);
+        for (const field of dependencyFields)
+            dependencyMap(entry, field, name);
+        if (entry.peerDependenciesMeta !== undefined) {
+            for (const [peer, metadata] of Object.entries(object(entry.peerDependenciesMeta, `${name} peerDependenciesMeta`))) {
+                packageName(peer);
+                const peerMetadata = object(metadata, `${name} peer metadata for ${peer}`);
+                if (peerMetadata.optional !== undefined && typeof peerMetadata.optional !== 'boolean')
+                    throw new Error(`${name}: invalid optional peer metadata for ${peer}`);
+            }
+        }
+        if (entry.engines !== undefined) {
+            if (Object.values(object(entry.engines, `${name} engines`)).some(value => typeof value !== 'string'))
+                throw new Error(`${name}: invalid engines metadata`);
+        }
+        for (const field of ['os', 'cpu', 'libc']) {
+            const value = entry[field];
+            if (value !== undefined && typeof value !== 'string' && (!Array.isArray(value) || value.some(item => typeof item !== 'string')))
+                throw new Error(`${name}: invalid ${field} metadata`);
+        }
+    }
+    return { text, lock: { lockfileVersion: 3, packages }, direct, key: ruleDependencyLockKey(parsed, directory) };
+}
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    if (value && typeof value === 'object') {
+        return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`).join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'undefined';
+}
+export function ruleDependencyLockKey(parsed, directory) {
+    if (parsed === null)
+        return 'empty';
+    const packages = object(parsed.packages, 'coderuler.lock packages');
+    const root = object(packages[''], 'coderuler.lock root package');
+    if (Object.keys(packages).length === 1 && Object.keys(dependencyMap(root, 'dependencies', 'coderuler.lock root')).length === 0)
+        return 'empty';
+    return createHash('sha256').update(JSON.stringify([
+        canonicalJson(parsed), directory, 1, process.version, process.platform, process.arch, currentEnv.libc(process.platform) ?? '',
+    ])).digest('hex');
+}
+export async function readRuleDependencyLock(directory) {
+    const path = join(directory, lockName);
+    let handle;
+    try {
+        const stat = await lstat(path);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            throw new Error(`${path}: dependency lock must be a regular, non-symlinked file`);
+        handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        if (!(await handle.stat()).isFile())
+            throw new Error(`${path}: dependency lock must be a regular file`);
+        return await handle.readFile('utf8');
+    }
+    catch (error) {
+        if (code(error) === 'ENOENT')
+            return null;
+        throw error;
+    }
+    finally {
+        await handle?.close();
+    }
+}
+async function ensureDependencyIgnore(directory) {
+    const path = join(directory, '.gitignore');
+    try {
+        const stat = await lstat(path);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            throw new Error(`${path}: dependency ignore must be a regular, non-symlinked file`);
+    }
+    catch (error) {
+        if (code(error) !== 'ENOENT')
+            throw error;
+    }
+    const handle = await open(path, constants.O_RDWR | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        if (!(await handle.stat()).isFile())
+            throw new Error(`${path}: dependency ignore must be a regular file`);
+        const text = await handle.readFile('utf8');
+        if (/^\/?node_modules\/?\r?$/m.test(text))
+            return;
+        const newline = text.includes('\r\n') ? '\r\n' : '\n';
+        await handle.writeFile(`${text.length > 0 && !text.endsWith('\n') ? newline : ''}/node_modules/${newline}`);
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function dependencyDirectory(ruleFile) {
+    const initial = dirname(await realpath(ruleFile));
+    let directory = initial;
+    for (;;) {
+        if (await readRuleDependencyLock(directory) !== null || basename(directory) === '.coderuler')
+            return directory;
+        const parent = dirname(directory);
+        if (parent === directory)
+            return initial;
+        directory = parent;
+    }
+}
+export class RegistryHttpsAgent extends Agent {
+    addRequest(request, options) {
+        const host = options.hostname ?? options.host;
+        if (host !== 'registry.npmjs.org' || (options.protocol !== undefined && options.protocol !== 'https:') || (options.port !== undefined && String(options.port) !== '443')) {
+            throw new Error('Rule dependency transport permits only https://registry.npmjs.org:443');
+        }
+        const prototype = Agent.prototype;
+        prototype.addRequest.call(this, request, options);
+    }
+}
+const agent = new RegistryHttpsAgent();
+const policy = {
+    registry, allowGit: 'none', allowRemote: 'none', allowFile: 'none', allowDirectory: 'none', allowRegistry: 'all',
+    ignoreScripts: true, strictSSL: true, replaceRegistryHost: 'never', agent, proxy: null, noProxy: '*',
+    binLinks: false, audit: false, fund: false, workspacesEnabled: false, lockfileVersion: 3,
+};
+function rootPackage(direct) {
+    return { ...rootIdentity, dependencies: Object.fromEntries(Object.entries(direct).sort(([a], [b]) => a.localeCompare(b))) };
+}
+function emptyLock() {
+    return `${JSON.stringify({ ...rootIdentity, lockfileVersion: 3, requires: true, packages: { '': rootPackage({}) } }, null, 2)}\n`;
+}
+async function stageLock(path, snapshot) {
+    await writeFile(join(path, 'package.json'), `${JSON.stringify(rootPackage(snapshot.direct), null, 2)}\n`);
+    await writeFile(join(path, 'package-lock.json'), snapshot.text);
+}
+async function inspectArtifacts(directory, label) {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+        const path = join(directory, entry.name);
+        if (entry.name === 'node_modules') {
+            throw new Error(`${label}: unsupported package artifact node_modules; bundled dependencies are unsupported`);
+        }
+        if (entry.name === 'binding.gyp' || entry.name.endsWith('.node') || entry.name === 'npm-shrinkwrap.json') {
+            throw new Error(`${label}: unsupported package artifact ${entry.name}; install-time builds, native addons, bundled dependencies and shrinkwraps are unsupported`);
+        }
+        if (entry.isDirectory())
+            await inspectArtifacts(path, label);
+    }
+}
+function comparable(manifest, field) {
+    if (dependencyFields.includes(field) || field === 'peerDependenciesMeta')
+        return manifest[field] ?? {};
+    const value = manifest[field];
+    if (value && typeof value === 'object' && Object.keys(value).length === 0)
+        return undefined;
+    return value;
+}
+async function validateExtracted(directory, location, locked) {
+    const name = locationName(location);
+    let raw;
+    try {
+        raw = object(JSON.parse(await readFile(join(directory, 'package.json'), 'utf8')), `${name} package.json`);
+    }
+    catch (error) {
+        throw new Error(`${name}: invalid extracted package.json`, { cause: error });
+    }
+    const scripts = raw.scripts === undefined ? {} : object(raw.scripts, `${name} scripts`);
+    if (['preinstall', 'install', 'postinstall'].some(script => Object.hasOwn(scripts, script))) {
+        throw new Error(`${name}: install scripts are unsupported; choose a package without install-time build artifacts`);
+    }
+    if (hasBundledDependencies(raw.bundleDependencies) || hasBundledDependencies(raw.bundledDependencies))
+        throw new Error(`${name}: bundled dependencies are unsupported`);
+    await inspectArtifacts(directory, name);
+    // A static import would load package validation tooling for every CLI invocation.
+    const { default: PackageJson } = await import('@npmcli/package-json');
+    const normalized = await new PackageJson().fromContent(structuredClone(raw)).normalize({ steps: PackageJson.normalizeSteps.filter(step => step !== '_attributes') });
+    const manifest = normalized.content;
+    for (const field of dependencyFields)
+        dependencyMap(manifest, field, name);
+    if (manifest.name !== name || manifest.version !== locked.version)
+        throw new Error(`${name}: extracted package name or version does not match coderuler.lock`);
+    for (const field of [...dependencyFields, 'peerDependenciesMeta', ...compatibilityFields]) {
+        if (!isDeepStrictEqual(comparable(manifest, field), comparable(locked, field)))
+            throw new Error(`${name}: extracted ${field} does not match coderuler.lock`);
+    }
+}
+async function regularDirectory(path) {
+    const stat = await lstat(path);
+    return stat.isDirectory() && !stat.isSymbolicLink();
+}
+async function installedLocally(directory, snapshot) {
+    try {
+        const modules = join(directory, 'node_modules');
+        if (!await regularDirectory(modules))
+            return false;
+        const markerPath = join(modules, markerName);
+        const stat = await lstat(markerPath);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            return false;
+        const marker = object(JSON.parse(await readFile(markerPath, 'utf8')), 'Rule dependency installation marker');
+        if (marker.version !== 1 || marker.key !== snapshot.key || !Array.isArray(marker.installedLocations))
+            return false;
+        const locations = new Set();
+        for (const location of marker.installedLocations) {
+            if (typeof location !== 'string' || !location || !snapshot.lock.packages[location] || locations.has(location))
+                return false;
+            locations.add(location);
+            let path = directory;
+            for (const segment of location.split('/')) {
+                path = join(path, segment);
+                if (!await regularDirectory(path))
+                    return false;
+            }
+            const packagePath = join(path, 'package.json');
+            const packageStat = await lstat(packagePath);
+            if (!packageStat.isFile() || packageStat.isSymbolicLink())
+                return false;
+            const manifest = object(JSON.parse(await readFile(packagePath, 'utf8')), packagePath);
+            if (manifest.name !== locationName(location) || manifest.version !== snapshot.lock.packages[location].version)
+                return false;
+        }
+        // Completion metadata cannot hide a missing direct or required transitive package.
+        for (const location of ['', ...locations]) {
+            const manifest = snapshot.lock.packages[location];
+            const optional = manifest.optionalDependencies ?? {};
+            const required = new Set(Object.keys(manifest.dependencies ?? {}).filter(name => !Object.hasOwn(optional, name)));
+            const peerMetadata = manifest.peerDependenciesMeta;
+            for (const name of Object.keys(manifest.peerDependencies ?? {})) {
+                if (!peerMetadata?.[name]?.optional)
+                    required.add(name);
+            }
+            for (const name of required) {
+                let parent = location;
+                let found = false;
+                for (;;) {
+                    if (locations.has(`${parent ? `${parent}/` : ''}node_modules/${name}`)) {
+                        found = true;
+                        break;
+                    }
+                    if (!parent)
+                        break;
+                    const split = parent.lastIndexOf('/node_modules/');
+                    parent = split < 0 ? '' : parent.slice(0, split);
+                }
+                if (!found)
+                    return false;
+            }
+        }
+        return true;
+    }
+    catch (error) {
+        if (code(error) && !['ENOENT', 'ENOTDIR'].includes(code(error)))
+            throw error;
+        return false;
+    }
+}
+async function install(directory, cacheRoot, previous, request) {
+    const stage = await realpath(await mkdtemp(join(directory, '.coderuler-deps-stage-')));
+    try {
+        let snapshot = previous;
+        let expected = [];
+        // An explicitly empty lock needs only an SDK installation, not npm graph work.
+        if (request || previous.key !== 'empty') {
+            await stageLock(stage, previous);
+            // A static import would load npm's graph stack during ordinary rule loading.
+            const { default: Arborist } = await import('@npmcli/arborist');
+            const arborist = new Arborist({ ...policy, engineStrict: true, savePrefix: '', path: stage, cache: join(cacheRoot, 'tarballs') });
+            const tree = await arborist.buildIdealTree(request);
+            const exact = Object.create(null);
+            for (const name of Object.keys(dependencyMap(tree.package, 'dependencies', 'resolved root')).sort()) {
+                const edge = tree.edgesOut.get(name);
+                if (!edge?.to || !edge.valid)
+                    throw new Error(`${name}: resolution did not produce a compatible direct package`);
+                exact[name] = exactVersion(name, edge.to.version);
+                if (!request && exact[name] !== previous.direct[name])
+                    throw new Error(`${name}: repair changed an exact direct dependency`);
+            }
+            tree.package = rootPackage(exact);
+            tree.meta.add(tree);
+            const serialized = `${JSON.stringify(JSON.parse(tree.meta.toString()), null, 2)}\n`;
+            snapshot = validateLock(isDeepStrictEqual(JSON.parse(previous.text), JSON.parse(serialized)) ? previous.text : serialized, directory);
+            const nodes = [...tree.inventory.values()].filter(node => node.location).map(node => ({ location: node.location, omitted: node.inert }));
+            expected = nodes.filter(node => !node.omitted).map(node => node.location);
+            for (const node of tree.inventory.values()) {
+                for (const edge of node.edgesOut.values()) {
+                    if (!edge.valid && !(edge.peer && edge.optional && !edge.to)) {
+                        throw new Error(`${node.location || 'coderuler.lock root'}: package resolution failed for dependency ${edge.name}`);
+                    }
+                }
+            }
+            for (const node of nodes) {
+                const entry = snapshot.lock.packages[node.location];
+                const audit = await mkdtemp(join(stage, '.audit-'));
+                try {
+                    // Inspect each raw artifact in isolation, including npm's omitted optional branches.
+                    // A static import would load registry extraction tooling during ordinary checks.
+                    const { default: pacote } = await import('pacote');
+                    await pacote.extract(entry.resolved, audit, { ...policy, allowRemote: 'all', integrity: entry.integrity, cache: join(cacheRoot, 'tarballs') });
+                    await validateExtracted(audit, node.location, entry);
+                }
+                finally {
+                    await rm(audit, { recursive: true, force: true });
+                }
+            }
+            await writeFile(join(stage, 'package.json'), `${JSON.stringify(rootPackage(exact), null, 2)}\n`);
+            const actual = await arborist.reify({ save: false });
+            for (const location of expected) {
+                if (!actual.inventory.get(location) || !await pathExists(join(stage, location))) {
+                    throw new Error(`${locationName(location)}: locked package acquisition failed; run coderuler deps sync after correcting the package or cache`);
+                }
+            }
+        }
+        const modules = join(stage, 'node_modules');
+        await mkdir(modules, { recursive: true });
+        const sdkTarget = await prepareRuleDependencySdk(directory, modules);
+        await writeFile(join(modules, markerName), `${JSON.stringify({
+            version: 1, key: snapshot.key, installedLocations: expected.sort(),
+            ...(sdkTarget === undefined ? {} : { sdkTarget }),
+        }, null, 2)}\n`);
+        return { snapshot, stage };
+    }
+    catch (error) {
+        await rm(stage, { recursive: true, force: true });
+        throw error;
+    }
+}
+function prepared(directory, snapshot) {
+    return {
+        directory,
+        directDependencies: Object.keys(snapshot?.direct ?? {}).sort(), key: snapshot?.key ?? 'empty',
+    };
+}
+function parsedPackages(operation, packages) {
+    if (packages.length === 0)
+        throw new Error(`coderuler deps ${operation} requires at least one package`);
+    const names = new Set();
+    return packages.map(value => {
+        const parsed = npa(value);
+        if (!parsed.name || !parsed.registry || !['version', 'range', 'tag'].includes(parsed.type))
+            throw new Error(`${JSON.stringify(value)}: only public npm package names, versions, ranges and tags are supported`);
+        const name = parsed.name;
+        if (operation === 'remove' && value !== name)
+            throw new Error(`${JSON.stringify(value)}: remove requires an unversioned direct package name`);
+        if (name === sdkName)
+            throw new Error(`${sdkName}: the SDK comes from the selected CodeRuler installation`);
+        if (names.has(name))
+            throw new Error(`${name}: duplicate package in dependency command`);
+        names.add(name);
+        return value;
+    });
+}
+async function pathExists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (code(error) === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+export function createRuleDependencyManager(options = {}) {
+    const cacheRoot = resolve(options.cacheRoot ?? join(homedir(), '.cache', 'coderuler', 'dependencies'));
+    const snapshotAt = async (directory) => {
+        const text = await readRuleDependencyLock(directory);
+        try {
+            return text === null ? null : validateLock(text, directory);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : 'invalid lock contents';
+            throw new Error(`${join(directory, lockName)}: ${detail}; use coderuler deps add to regenerate the lock`, { cause: error });
+        }
+    };
+    const publish = async (directory, previousLock, installation) => {
+        try {
+            if (await readRuleDependencyLock(directory) !== previousLock)
+                throw new Error(`${join(directory, lockName)}: dependency lock changed during installation; rerun coderuler deps sync`);
+            await ensureDependencyIgnore(directory);
+        }
+        catch (error) {
+            await rm(installation.stage, { recursive: true, force: true });
+            throw error;
+        }
+        // Publication takes ownership of staging, including any rollback backup.
+        await publishRuleDependencyInstallation({
+            directory, stage: installation.stage, previousLock, nextLock: installation.snapshot.text,
+            ...(options.onWarning === undefined ? {} : { onWarning: options.onWarning }),
+        });
+        return prepared(directory, installation.snapshot);
+    };
+    const prepare = async (input, explicit) => {
+        const directory = await realpath(input);
+        if (!explicit && !await pathExists(join(directory, '.coderuler-deps-write'))) {
+            const snapshot = await snapshotAt(directory);
+            if ((!snapshot || snapshot.key === 'empty' || await installedLocally(directory, snapshot))
+                && !await pathExists(join(directory, '.coderuler-deps-write'))
+                && await readRuleDependencyLock(directory) === (snapshot?.text ?? null))
+                return prepared(directory, snapshot);
+        }
+        return withRuleDependencyDirectoryLock(directory, async () => {
+            const snapshot = await snapshotAt(directory);
+            if (!snapshot) {
+                if (explicit)
+                    await prepareRuleDependencySdk(directory, join(directory, 'node_modules'));
+                return prepared(directory, snapshot);
+            }
+            if (snapshot.key === 'empty' && !explicit)
+                return prepared(directory, snapshot);
+            if (await installedLocally(directory, snapshot)) {
+                if (explicit) {
+                    await prepareRuleDependencySdk(directory, join(directory, 'node_modules'));
+                    await ensureDependencyIgnore(directory);
+                }
+                return prepared(directory, snapshot);
+            }
+            return publish(directory, snapshot.text, await install(directory, cacheRoot, snapshot));
+        }, options.onWarning);
+    };
+    return {
+        prepare: directory => prepare(directory, false),
+        sync: directory => prepare(directory, true),
+        async change(input, operation, requested) {
+            const packages = parsedPackages(operation, requested);
+            if (operation === 'add')
+                await mkdir(input, { recursive: true });
+            const directory = await realpath(input);
+            return withRuleDependencyDirectoryLock(directory, async () => {
+                const previous = await readRuleDependencyLock(directory);
+                const snapshot = validateLock(previous ?? emptyLock(), directory);
+                if (operation === 'remove') {
+                    for (const name of packages)
+                        if (!Object.hasOwn(snapshot.direct, name))
+                            throw new Error(`${name}: not a declared direct dependency`);
+                }
+                const installation = await install(directory, cacheRoot, snapshot, operation === 'add' ? { add: packages } : { rm: packages });
+                const result = await publish(directory, previous, installation);
+                return { ...result, directVersions: installation.snapshot.direct };
+            }, options.onWarning);
+        },
+    };
+}

package/dist/adapter/filesystem/dependency-installation.d.ts

@@ -0,0 +1,11 @@
+export declare function withRuleDependencyDirectoryLock<T>(ownerDirectory: string, action: () => Promise<T>, onWarning?: (message: string) => void): Promise<T>;
+/** Called under the owner mutex. Only the SDK may be a generated package link. */
+export declare function prepareRuleDependencySdk(ownerDirectory: string, nodeModules: string): Promise<string | undefined>;
+/** Takes ownership of stage. The caller holds the owner mutex throughout publication. */
+export declare function publishRuleDependencyInstallation(options: {
+    readonly directory: string;
+    readonly stage: string;
+    readonly previousLock: string | null;
+    readonly nextLock: string;
+    readonly onWarning?: (message: string) => void;
+}): Promise<void>;