@dokebi/cli 0.0.0-stage → 0.1.0

package/dist/plugin-options.js

@@ -0,0 +1,53 @@
+// [AI:생성] 설치 코드 실행 없이 표준 JSON Schema로 옵션을 검증하고 설정을 그대로 보존한다.
+import { readFile } from 'node:fs/promises';
+import { CliError } from './errors.js';
+import { parseObject, securePath } from './filesystem.js';
+// [AI:수정] CLI 진단·스키마·회귀 검증의 포맷과 import 순서를 맞춘다.
+export async function checkPluginOptions(root, plugin, options) {
+    if (!plugin.optionsSchema)
+        return { schema: null, errors: [] };
+    const path = 'node_modules/' + plugin.packageName + '/' + plugin.optionsSchema;
+    const text = await readFile(await securePath(root, path), 'utf8');
+    if (Buffer.byteLength(text) > 131072)
+        throw new CliError('INVALID_OPTIONS_SCHEMA', plugin.id);
+    let schema;
+    try {
+        schema = parseObject(text, 'options schema');
+        if (schema.$schema !== 'https://json-schema.org/draft/2020-12/schema' ||
+            schema.type !== 'object')
+            throw new Error('Expected draft 2020-12 object schema');
+        const { Ajv2020 } = await import('ajv/dist/2020.js');
+        const ajv = new Ajv2020({
+            strict: true,
+            allErrors: false,
+            coerceTypes: false,
+            useDefaults: false,
+            removeAdditional: false,
+            ownProperties: true,
+        });
+        const validate = ajv.compile(schema);
+        // [AI:수정] Ajv의 동기 검증 함수 타입을 유지하면서 비동기 스키마를 명시적으로 거부한다.
+        if ('$async' in validate && validate.$async)
+            throw new Error('Async schemas are unsupported');
+        const valid = validate(options);
+        return {
+            schema,
+            errors: valid
+                ? []
+                : (validate.errors ?? []).map(({ instancePath, keyword }) => ({ instancePath, keyword })),
+        };
+    }
+    catch (cause) {
+        throw new CliError('INVALID_OPTIONS_SCHEMA', plugin.id, { cause });
+    }
+}
+export async function validatePluginOptions(root, plugins, options) {
+    for (const plugin of plugins) {
+        // [AI:수정] 추가한 버전·옵션 경계 검사를 저장소 포맷에 맞춘다.
+        const result = await checkPluginOptions(root, plugin, Object.hasOwn(options, plugin.id) ? (options[plugin.id] ?? {}) : {});
+        if (result.errors.length)
+            throw new CliError('INVALID_PLUGIN_OPTIONS', plugin.id, {
+                details: { plugin: plugin.id, errors: result.errors },
+            });
+    }
+}

package/dist/project-guide.d.ts

@@ -0,0 +1 @@
+export declare const PROJECT_GUIDE = "# Dokebi \uD504\uB85C\uC81D\uD2B8 \uC791\uC5C5 \uC548\uB0B4\n\n\uC124\uCE58\uB41C \uCF54\uC5B4 \uACC4\uC57D\uC740 [\uCF54\uC5B4 AI \uC0AC\uC6A9 \uC548\uB0B4](node_modules/@dokebi/core/AI.md)\uB97C \uC77D\uB294\uB2E4.\n\uD328\uD0A4\uC9C0 \uBC84\uC804\uC740 package.json\uACFC \uC2E4\uC81C node_modules\uB97C \uD568\uAED8 \uD655\uC778\uD55C\uB2E4.\n\n- \uD504\uB85C\uC81D\uD2B8 \uB8E8\uD2B8\uC5D0\uC11C \uC124\uCE58\uB41C CLI\uB85C dokebi inspect --json, dokebi doctor --json\uC744 \uC2E4\uD589\uD55C\uB2E4.\n- inspect\uC5D0 \uB098\uC628 \uD50C\uB7EC\uADF8\uC778 documentation\uACFC optionsSchema\uB97C \uD655\uC778\uD55C\uB2E4.\n- src/main.ts\uB294 \uC0AC\uC6A9\uC790 \uC9C4\uC785\uC810, dokebi.json\uC740 \uC0AC\uC6A9\uC790 \uC635\uC158\uC774\uB2E4.\n- src/dokebi.generated.ts\uC640 .dokebi/state.json\uC740 \uC9C1\uC811 \uD3B8\uC9D1\uD558\uC9C0 \uC54A\uB294\uB2E4.\n- add\uB294 \uD328\uD0A4\uC9C0 \uC9C0\uC815, remove\uB294 \uD50C\uB7EC\uADF8\uC778 ID\uB97C \uBC1B\uB294\uB2E4. \uBA3C\uC800 --dry-run\uC73C\uB85C \uAC80\uD1A0\uD55C\uB2E4.\n- doctor\uB294 \uC790\uB3D9 \uBCF5\uAD6C\uD558\uC9C0 \uC54A\uB294\uB2E4. \uC7A0\uAE08\uC774\uB098 \uBC31\uC5C5\uC744 \uC784\uC758 \uC0AD\uC81C\uD558\uAC70\uB098 \uC2E4\uD328\uB97C \uBB34\uC870\uAC74 \uC7AC\uC2DC\uB3C4\uD558\uC9C0 \uC54A\uB294\uB2E4.\n- \uBCC0\uACBD \uD6C4 npm start\uC640 \uD504\uB85C\uC81D\uD2B8\uBCC4 \uD14C\uC2A4\uD2B8\uB97C \uC2E4\uD589\uD55C\uB2E4.\n";

package/dist/project-guide.js

@@ -0,0 +1,14 @@
+// [AI:생성] 플러그인과 설치 버전의 사용 계약을 AI가 추측 없이 확인하게 한다.
+export const PROJECT_GUIDE = `# Dokebi 프로젝트 작업 안내
+
+설치된 코어 계약은 [코어 AI 사용 안내](node_modules/@dokebi/core/AI.md)를 읽는다.
+패키지 버전은 package.json과 실제 node_modules를 함께 확인한다.
+
+- 프로젝트 루트에서 설치된 CLI로 dokebi inspect --json, dokebi doctor --json을 실행한다.
+- inspect에 나온 플러그인 documentation과 optionsSchema를 확인한다.
+- src/main.ts는 사용자 진입점, dokebi.json은 사용자 옵션이다.
+- src/dokebi.generated.ts와 .dokebi/state.json은 직접 편집하지 않는다.
+- add는 패키지 지정, remove는 플러그인 ID를 받는다. 먼저 --dry-run으로 검토한다.
+- doctor는 자동 복구하지 않는다. 잠금이나 백업을 임의 삭제하거나 실패를 무조건 재시도하지 않는다.
+- 변경 후 npm start와 프로젝트별 테스트를 실행한다.
+`;

package/dist/project-inspector.d.ts

@@ -0,0 +1,24 @@
+import { type PluginManifest } from './manifest.js';
+export interface Diagnostic {
+    code: string;
+    severity: 'error' | 'warning';
+    path: string;
+    plugin: string | null;
+    details?: unknown;
+}
+export interface Inspection {
+    root: string;
+    healthy: boolean;
+    coreVersion: string | null;
+    plugins: Array<{
+        expected: PluginManifest;
+        installed: PluginManifest | null;
+        optionKeys: string[];
+        optionsSchema: Record<string, unknown> | null;
+        documentation: string | null;
+    }>;
+    diagnostics: Diagnostic[];
+}
+export declare class ProjectInspector {
+    inspect(directory: string): Promise<Inspection>;
+}

package/dist/project-inspector.js

@@ -0,0 +1,153 @@
+// [AI:수정] CLI 진단·스키마·회귀 검증의 포맷과 import 순서를 맞춘다.
+import { readdir, readFile, realpath } from 'node:fs/promises';
+// [AI:수정] 설치 버전과 package.json의 요청 범위가 다른 경우도 진단한다.
+import satisfies from 'semver/functions/satisfies.js';
+import valid from 'semver/functions/valid.js';
+import { CliError } from './errors.js';
+import { exists, fingerprint, hash, json, parseObject, securePath } from './filesystem.js';
+import { orderPlugins, readManifest } from './manifest.js';
+import { dependencyMap, validateProjectPackage } from './npm-client.js';
+// [AI:수정] 설치 버전의 옵션 스키마와 문서 위치를 공개하고 옵션 오류를 진단한다.
+import { checkPluginOptions } from './plugin-options.js';
+import { readConfig, readState } from './project-state.js';
+// Reads metadata only. Never imports plugin entry points or creates locks.
+export class ProjectInspector {
+    async inspect(directory) {
+        const root = await realpath(directory);
+        const result = {
+            root,
+            healthy: false,
+            coreVersion: null,
+            plugins: [],
+            diagnostics: [],
+        };
+        const originals = new Map();
+        const issue = (code, path, plugin = null, severity = 'error') => {
+            result.diagnostics.push({ code, path, plugin, severity });
+        };
+        const check = async (path, action, plugin = null) => {
+            try {
+                return await action();
+            }
+            catch (error) {
+                const code = error instanceof CliError
+                    ? error.code
+                    : error instanceof Error && 'code' in error && typeof error.code === 'string'
+                        ? error.code
+                        : 'READ_FAILED';
+                issue(code, path, plugin);
+                return null;
+            }
+        };
+        const read = async (path) => {
+            const text = await readFile(await securePath(root, path), 'utf8');
+            originals.set(path, hash(text));
+            return text;
+        };
+        const state = await check('.dokebi/state.json', async () => readState(parseObject(await read('.dokebi/state.json'), 'state')));
+        const config = await check('dokebi.json', async () => readConfig(parseObject(await read('dokebi.json'), 'config')));
+        const pkg = await check('package.json', async () => {
+            const value = parseObject(await read('package.json'), 'package');
+            validateProjectPackage(value);
+            return dependencyMap(value);
+        });
+        const corePath = 'node_modules/@dokebi/core/package.json';
+        const core = await check(corePath, async () => {
+            const value = parseObject(await read(corePath), 'core');
+            if (value.name !== '@dokebi/core' ||
+                typeof value.version !== 'string' ||
+                !valid(value.version))
+                throw new CliError('INVALID_CORE', 'Invalid core identity');
+            return value.version;
+        });
+        result.coreVersion = core;
+        const matches = (name, version, plugin) => {
+            const spec = pkg?.[name];
+            if (spec && !spec.startsWith('file:') && !satisfies(version, spec))
+                issue('PACKAGE_VERSION_MISMATCH', 'package.json', plugin);
+        };
+        if (core)
+            matches('@dokebi/core', core, null);
+        if (pkg && !Object.hasOwn(pkg, '@dokebi/core'))
+            issue('MISSING_CORE_DEPENDENCY', 'package.json');
+        const generated = await check('src/dokebi.generated.ts', () => read('src/dokebi.generated.ts'));
+        if (state && generated !== null && hash(generated) !== state.generatedHash)
+            issue('MODIFIED_REGISTRATION', 'src/dokebi.generated.ts');
+        const control = await check('.dokebi', async () => readdir(await securePath(root, '.dokebi')));
+        if (control?.includes('lock'))
+            issue('PROJECT_LOCKED', '.dokebi/lock');
+        for (const name of control ?? []) {
+            if (name.startsWith('transaction-'))
+                issue('RECOVERY_REQUIRED', '.dokebi/' + name);
+        }
+        if (state) {
+            for (const plugin of state.plugins) {
+                const path = 'node_modules/' + plugin.packageName + '/package.json';
+                const installed = await check(path, async () => readManifest(parseObject(await read(path), 'plugin')), plugin.id);
+                if (installed && json(installed) !== json(plugin))
+                    issue('MANIFEST_CHANGED', path, plugin.id);
+                if (pkg && !Object.hasOwn(pkg, plugin.packageName))
+                    issue('MISSING_PACKAGE_DEPENDENCY', 'package.json', plugin.id);
+                if (installed)
+                    matches(installed.packageName, installed.version, plugin.id);
+                // [AI:수정] 추가한 버전·옵션 경계 검사를 저장소 포맷에 맞춘다.
+                const options = config && Object.hasOwn(config.options, plugin.id)
+                    ? config.options[plugin.id]
+                    : undefined;
+                const checked = installed
+                    ? await check(path, async () => checkPluginOptions(root, installed, options ?? {}), plugin.id)
+                    : null;
+                if (checked?.errors.length)
+                    result.diagnostics.push({
+                        code: 'INVALID_PLUGIN_OPTIONS',
+                        severity: 'error',
+                        path: 'dokebi.json',
+                        plugin: plugin.id,
+                        details: checked.errors,
+                    });
+                let documentation = null;
+                if (installed?.documentation) {
+                    const candidate = 'node_modules/' + installed.packageName + '/' + installed.documentation;
+                    const guide = await check(candidate, () => read(candidate), plugin.id);
+                    if (guide !== null)
+                        documentation = candidate;
+                }
+                result.plugins.push({
+                    expected: plugin,
+                    installed,
+                    optionsSchema: checked?.schema ?? null,
+                    documentation,
+                    optionKeys: options && typeof options === 'object' && !Array.isArray(options)
+                        ? Object.keys(options)
+                        : [],
+                });
+            }
+            if (core)
+                await check('.dokebi/state.json', async () => orderPlugins(state.plugins, core));
+            for (const [path, owned] of Object.entries(state.files)) {
+                const actual = await check(path, async () => fingerprint(await securePath(root, path)));
+                if (actual !== owned.hash)
+                    issue('MODIFIED_TEMPLATE', path, null, 'warning');
+            }
+            for (const id of Object.keys(config?.options ?? {})) {
+                if (!state.plugins.some((plugin) => plugin.id === id))
+                    issue('ORPHAN_OPTIONS', 'dokebi.json', id, 'warning');
+            }
+        }
+        for (const [path, expected] of originals) {
+            await check(path, async () => {
+                if (hash(await readFile(await securePath(root, path))) !== expected)
+                    throw new CliError('CONCURRENT_CHANGE', 'Metadata changed during inspection');
+                return true;
+            });
+        }
+        await check('.dokebi/lock', async () => {
+            if ((await exists(await securePath(root, '.dokebi/lock'))) &&
+                !result.diagnostics.some((item) => item.code === 'PROJECT_LOCKED'))
+                issue('PROJECT_LOCKED', '.dokebi/lock');
+            return true;
+        });
+        result.healthy = !result.diagnostics.some((item) => item.severity === 'error');
+        return result;
+    }
+}

package/dist/project-state.d.ts

@@ -0,0 +1,18 @@
+import { type PluginManifest } from './manifest.js';
+export interface OwnedFile {
+    hash: string;
+    owners: string[];
+}
+export interface ProjectState {
+    schemaVersion: 1;
+    plugins: PluginManifest[];
+    files: Record<string, OwnedFile>;
+    generatedHash: string;
+}
+export interface ProjectConfig {
+    schemaVersion: 1;
+    options: Record<string, unknown>;
+}
+export declare function emptyState(generatedHash: string): ProjectState;
+export declare function readState(value: unknown): ProjectState;
+export declare function readConfig(value: unknown): ProjectConfig;

package/dist/project-state.js

@@ -0,0 +1,45 @@
+// [AI:생성] 설치 중 플러그인 코드를 실행하지 않고 실제 인스턴스로 의존 플러그인을 연결한다.
+import { CliError } from './errors.js';
+import { object, templateTarget } from './filesystem.js';
+import { readManifest } from './manifest.js';
+export function emptyState(generatedHash) {
+    return { schemaVersion: 1, plugins: [], files: Object.create(null), generatedHash };
+}
+export function readState(value) {
+    const input = object(value, 'state');
+    if (input.schemaVersion !== 1 ||
+        !Array.isArray(input.plugins) ||
+        typeof input.generatedHash !== 'string')
+        throw new CliError('INVALID_STATE', 'Unsupported project state');
+    const plugins = input.plugins.map((entry) => {
+        const plugin = object(entry, 'plugin');
+        return readManifest({
+            name: plugin.packageName,
+            version: plugin.version,
+            dokebi: { ...plugin, schemaVersion: 1 },
+        });
+    });
+    if (new Set(plugins.map((plugin) => plugin.id)).size !== plugins.length ||
+        new Set(plugins.map((plugin) => plugin.packageName)).size !== plugins.length)
+        throw new CliError('INVALID_STATE', 'Duplicate installed plugin');
+    const files = Object.create(null);
+    for (const [path, value] of Object.entries(object(input.files, 'files'))) {
+        templateTarget(path);
+        const file = object(value, 'file');
+        if (typeof file.hash !== 'string' ||
+            !/^[a-f0-9]{64}$/.test(file.hash) ||
+            !Array.isArray(file.owners) ||
+            !file.owners.length ||
+            !file.owners.every((owner) => typeof owner === 'string' && plugins.some((plugin) => plugin.id === owner)) ||
+            new Set(file.owners).size !== file.owners.length)
+            throw new CliError('INVALID_STATE', 'Invalid file ownership');
+        files[path] = { hash: file.hash, owners: file.owners };
+    }
+    return { schemaVersion: 1, plugins, files, generatedHash: input.generatedHash };
+}
+export function readConfig(value) {
+    const config = object(value, 'config');
+    if (config.schemaVersion !== 1)
+        throw new CliError('INVALID_CONFIG', 'Unsupported config');
+    return { schemaVersion: 1, options: object(config.options, 'options') };
+}

package/dist/project.d.ts

@@ -0,0 +1,16 @@
+import { NpmClient } from './npm-client.js';
+export interface OperationResult {
+    changed: string[];
+    preserved: string[];
+}
+export declare class Project {
+    private readonly npm;
+    constructor(npm?: NpmClient);
+    init(target: string, core?: string): Promise<OperationResult>;
+    add(root: string, spec: string, dryRun?: boolean): Promise<OperationResult>;
+    remove(root: string, id: string, dryRun?: boolean): Promise<OperationResult>;
+    private coreVersion;
+    private change;
+    private addFiles;
+    private writeConfiguration;
+}

package/dist/project.js

@@ -0,0 +1,210 @@
+// [AI:수정] 빈 디렉터리에 맞는 제거 API를 사용하고 정리 실패를 숨기지 않는다.
+import { mkdir, mkdtemp, readFile, realpath, rename, rm, rmdir, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { CliError } from './errors.js';
+import { exists, fingerprint, hash, json, parseObject, securePath } from './filesystem.js';
+import { generateRegistration, MAIN_SOURCE } from './generator.js';
+import { orderPlugins, readManifest } from './manifest.js';
+import { dependencyMap, NpmClient, packageSpec, validateProjectPackage } from './npm-client.js';
+// [AI:수정] CLI 진단·스키마·회귀 검증의 포맷과 import 순서를 맞춘다.
+import { validatePluginOptions } from './plugin-options.js';
+// [AI:수정] 새 프로젝트에 설치 버전 계약과 CLI 진단을 안내하는 짧은 AI 시작 문서를 생성한다.
+import { PROJECT_GUIDE } from './project-guide.js';
+import { emptyState, readConfig, readState, } from './project-state.js';
+import { Transaction } from './transaction.js';
+const GENERATED = 'src/dokebi.generated.ts';
+export class Project {
+    npm;
+    constructor(npm = new NpmClient()) {
+        this.npm = npm;
+    }
+    async init(target, core = '@dokebi/core@0.1.0') {
+        target = resolve(target);
+        if (await exists(target))
+            throw new CliError('PROJECT_EXISTS', target);
+        const parent = await realpath(dirname(target));
+        const staging = await mkdtemp(join(parent, '.dokebi-init-'));
+        try {
+            await mkdir(join(staging, 'src'));
+            await mkdir(join(staging, '.dokebi'));
+            await writeFile(join(staging, 'package.json'), json({
+                name: basename(target)
+                    .toLowerCase()
+                    .replace(/[^a-z0-9-]/g, '-') || 'dokebi-app',
+                private: true,
+                type: 'module',
+                scripts: { start: 'node src/main.ts' },
+                engines: { node: '^24.21.0 || ^26.11.1' },
+            }));
+            await this.npm.install(staging, packageSpec(core, process.cwd()));
+            await this.coreVersion(staging);
+            const generated = generateRegistration([]);
+            await writeFile(join(staging, GENERATED), generated);
+            await writeFile(join(staging, 'src/main.ts'), MAIN_SOURCE);
+            await writeFile(join(staging, 'AGENTS.md'), PROJECT_GUIDE);
+            await writeFile(join(staging, 'dokebi.json'), json({ schemaVersion: 1, options: {} }));
+            await writeFile(join(staging, '.dokebi/state.json'), json(emptyState(hash(generated))));
+            await writeFile(join(staging, '.gitignore'), 'node_modules/\n.dokebi/lock\n.dokebi/transaction-*/\n');
+            // Reserve the destination before moving anything so existing projects are never replaced.
+            await mkdir(target);
+            try {
+                await rename(staging, target);
+            }
+            catch (cause) {
+                try {
+                    await rmdir(target);
+                }
+                catch (cleanup) {
+                    // [AI:수정] 초기화 실패 오류 보존 코드의 포맷을 맞춘다.
+                    throw new AggregateError([cause, cleanup], 'Initialization and destination cleanup failed');
+                }
+                throw cause;
+            }
+            return { changed: [target], preserved: [] };
+        }
+        finally {
+            await rm(staging, { recursive: true, force: true });
+        }
+    }
+    async add(root, spec, dryRun = false) {
+        return this.change(root, { add: packageSpec(spec, root) }, dryRun);
+    }
+    async remove(root, id, dryRun = false) {
+        return this.change(root, { remove: id }, dryRun);
+    }
+    async coreVersion(root) {
+        const pkg = parseObject(await readFile(await securePath(root, 'node_modules/@dokebi/core/package.json'), 'utf8'), 'core');
+        if (pkg.name !== '@dokebi/core' || typeof pkg.version !== 'string')
+            throw new CliError('INVALID_CORE', 'Missing Dokebi core');
+        return pkg.version;
+    }
+    async change(root, operation, dryRun) {
+        root = await realpath(root);
+        // Do not create control files in arbitrary non-Dokebi projects.
+        await readFile(await securePath(root, '.dokebi/state.json'));
+        const tx = await Transaction.begin(root);
+        try {
+            const state = readState(JSON.parse(await tx.read('.dokebi/state.json')));
+            const config = readConfig(JSON.parse(await tx.read('dokebi.json')));
+            const pkg = parseObject(await tx.read('package.json'), 'package.json');
+            validateProjectPackage(pkg);
+            if (hash(await tx.read(GENERATED)) !== state.generatedHash)
+                throw new CliError('MODIFIED_REGISTRATION', GENERATED);
+            const dependencies = dependencyMap(pkg);
+            const removed = 'remove' in operation
+                ? state.plugins.find((plugin) => plugin.id === operation.remove)
+                : undefined;
+            if ('remove' in operation && !removed)
+                return { changed: [], preserved: [] };
+            if (removed &&
+                state.plugins.some((plugin) => plugin.dependencies.some((dep) => dep.name === removed.id))) {
+                throw new CliError('REVERSE_DEPENDENCY', removed.id);
+            }
+            const staging = join(tx.directory, 'npm');
+            await mkdir(staging);
+            if (removed)
+                delete dependencies[removed.packageName];
+            pkg.dependencies = dependencies;
+            await writeFile(join(staging, 'package.json'), json(pkg));
+            const lock = await securePath(root, 'package-lock.json');
+            if (await exists(lock))
+                await writeFile(join(staging, 'package-lock.json'), await tx.read('package-lock.json'));
+            await tx.capture('node_modules');
+            await this.npm.install(staging, 'add' in operation ? operation.add : undefined);
+            const installed = parseObject(await readFile(join(staging, 'package.json'), 'utf8'), 'installed package');
+            const after = dependencyMap(installed);
+            let added;
+            if ('add' in operation) {
+                const name = operation.add.startsWith('file:')
+                    ? Object.keys(after).find((key) => after[key] === operation.add)
+                    : /^(@[^/]+\/[^@]+|[^@]+)/.exec(operation.add)?.[1];
+                if (!name || !Object.hasOwn(after, name))
+                    throw new CliError('INVALID_PACKAGE', 'Cannot identify installed package');
+                added = readManifest(parseObject(await readFile(await securePath(staging, 'node_modules/' + name + '/package.json'), 'utf8'), name));
+                const existing = state.plugins.find((plugin) => plugin.id === added?.id || plugin.packageName === added?.packageName);
+                if (existing) {
+                    if (existing.id === added.id &&
+                        existing.packageName === added.packageName &&
+                        existing.version === added.version)
+                        return { changed: [], preserved: [] };
+                    throw new CliError('UPGRADE_UNSUPPORTED', added.id);
+                }
+                if (Object.hasOwn(dependencies, name))
+                    throw new CliError('PACKAGE_CONFLICT', name);
+            }
+            const next = state.plugins.filter((plugin) => plugin.id !== removed?.id);
+            if (added)
+                next.push(added);
+            // npm must not silently alter the identity/version of previously registered plugins.
+            for (const plugin of next) {
+                const actual = readManifest(JSON.parse(await readFile(await securePath(staging, 'node_modules/' + plugin.packageName + '/package.json'), 'utf8')));
+                if (json(actual) !== json(plugin))
+                    throw new CliError('MANIFEST_CHANGED', plugin.id);
+            }
+            const ordered = orderPlugins(next, await this.coreVersion(staging));
+            await validatePluginOptions(staging, ordered, config.options);
+            const preserved = [];
+            if (added)
+                await this.addFiles(tx, staging, state, added);
+            if (removed) {
+                for (const [path, file] of Object.entries(state.files)) {
+                    if (!file.owners.includes(removed.id))
+                        continue;
+                    file.owners = file.owners.filter((owner) => owner !== removed.id);
+                    if (file.owners.length)
+                        continue;
+                    await tx.capture(path);
+                    const current = await fingerprint(await securePath(root, path));
+                    if (current === file.hash)
+                        await tx.replace(path);
+                    else if (current !== null)
+                        preserved.push(path);
+                    delete state.files[path];
+                }
+                delete config.options[removed.id];
+            }
+            if (added && !Object.hasOwn(config.options, added.id))
+                config.options[added.id] = {};
+            state.plugins = ordered;
+            await this.writeConfiguration(tx, state, config);
+            await tx.replace('package.json', join(staging, 'package.json'));
+            await tx.replace('package-lock.json', join(staging, 'package-lock.json'));
+            await tx.replace('node_modules', join(staging, 'node_modules'));
+            const result = { changed: tx.paths, preserved };
+            if (!dryRun)
+                await tx.commit();
+            return result;
+        }
+        finally {
+            await tx.close();
+        }
+    }
+    async addFiles(tx, staging, state, plugin) {
+        for (const file of plugin.files) {
+            const source = await securePath(staging, 'node_modules/' + plugin.packageName + '/' + file.source);
+            const content = await readFile(source);
+            const digest = hash(content);
+            await tx.capture(file.target);
+            const current = await fingerprint(await securePath(tx.root, file.target));
+            const owned = state.files[file.target];
+            if (owned) {
+                if (current !== digest || owned.hash !== digest)
+                    throw new CliError('FILE_CONFLICT', file.target);
+                owned.owners.push(plugin.id);
+            }
+            else {
+                if (current !== null)
+                    throw new CliError('FILE_CONFLICT', file.target);
+                await tx.write(file.target, content);
+                state.files[file.target] = { hash: digest, owners: [plugin.id] };
+            }
+        }
+    }
+    async writeConfiguration(tx, state, config) {
+        const generated = generateRegistration(state.plugins);
+        state.generatedHash = hash(generated);
+        await tx.write(GENERATED, generated);
+        await tx.write('dokebi.json', json(config));
+        await tx.write('.dokebi/state.json', json(state));
+    }
+}

package/dist/transaction.d.ts

@@ -0,0 +1,14 @@
+export declare class Transaction {
+    #private;
+    readonly root: string;
+    readonly directory: string;
+    private constructor();
+    static begin(root: string): Promise<Transaction>;
+    capture(path: string): Promise<void>;
+    read(path: string): Promise<string>;
+    write(path: string, content: string | Uint8Array): Promise<void>;
+    replace(path: string, source?: string): Promise<void>;
+    get paths(): string[];
+    commit(beforeApply?: (index: number) => void): Promise<void>;
+    close(): Promise<void>;
+}