@dokebi/cli 0.1.1 → 0.2.2

package/dist/project.js

@@ -1,25 +1,37 @@
-// [AI:수정] 빈 디렉터리에 맞는 제거 API를 사용하고 정리 실패를 숨기지 않는다.
-import { mkdir, mkdtemp, readFile, realpath, rename, rm, rmdir, writeFile } from 'node:fs/promises';
+import { mkdir, mkdtemp, readdir, readFile, realpath, rename, rm, rmdir, writeFile, } from 'node:fs/promises';
 import { basename, dirname, join, resolve } from 'node:path';
+import lt from 'semver/functions/lt.js';
+import satisfies from 'semver/functions/satisfies.js';
+import validRange from 'semver/ranges/valid.js';
+import { applyConfigChanges, applySetOptions, markRemoved, setWarnings, } from './config-edit.js';
+import { CONFIG_BACKUP, CONFIG_EXAMPLE, CONFIG_FILE, CONFIG_TEMPLATE, ignoreConfig, LEGACY_CONFIG_FILE, migrateConfig, parseProjectConfig, } from './configuration.js';
+import { scaffoldConfig } from './configuration-scaffold.js';
 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 { markExampleRemoved, syncExample } from './example-config.js';
+import { exists, fingerprint, hash, json, object, parseObject, securePath, templateTarget, } from './filesystem.js';
+import { generateRegistration, LEGACY_MAIN_SOURCE, MAIN_SOURCE, MAIN_SOURCE_V1, TSCONFIG_SOURCE, } from './generator.js';
+import { orderPlugins, PACKAGE_NAME, readManifest, } from './manifest.js';
+import { mergeInstallDefaults } from './merge-install-defaults.js';
 import { dependencyMap, NpmClient, packageSpec, validateProjectPackage } from './npm-client.js';
-// [AI:수정] CLI 진단·스키마·회귀 검증의 포맷과 import 순서를 맞춘다.
-import { validatePluginOptions } from './plugin-options.js';
-// [AI:수정] 새 프로젝트에 설치 버전 계약과 CLI 진단을 안내하는 짧은 AI 시작 문서를 생성한다.
+import { checkAll, optionsOf, planLifecycle, } from './plugin-lifecycle.js';
+import { PluginOptionsValidator, validatePluginOptions } from './plugin-options.js';
 import { PROJECT_GUIDE } from './project-guide.js';
-import { emptyState, readConfig, readState, } from './project-state.js';
+import { APP_NAME, defaultInstallation, emptyState, readState, } from './project-state.js';
+import { readRequiredPlugins } from './required-plugins.js';
 import { Transaction } from './transaction.js';
+import { installedPath, packageFile, workspacePackages, workspaceRootOf, } from './workspace.js';
 const GENERATED = 'src/dokebi.generated.ts';
+const EXAMPLE = 'dokebi.example.yaml';
+const DEPENDENCY_SECTIONS = ['dependencies', 'devDependencies', 'optionalDependencies'];
+function union(...lists) {
+    return [...new Set(lists.flat())];
+}
 export class Project {
     npm;
     constructor(npm = new NpmClient()) {
         this.npm = npm;
     }
-    // [AI:수정] 새 프로젝트의 기본 코어를 같은 패치 릴리스로 고정한다.
-    async init(target, core = '@dokebi/core@0.1.1') {
+    async init(target, core = '@dokebi/core@0.2.2') {
         target = resolve(target);
         if (await exists(target))
             throw new CliError('PROJECT_EXISTS', target);
@@ -35,17 +47,20 @@ export class Project {
                 private: true,
                 type: 'module',
                 scripts: { start: 'node src/main.ts' },
-                engines: { node: '^24.21.0 || ^26.11.1' },
+                engines: { node: '>=24.0.0' },
             }));
             await this.npm.install(staging, packageSpec(core, process.cwd()));
             await this.coreVersion(staging);
+            await readRequiredPlugins(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, 'tsconfig.json'), TSCONFIG_SOURCE);
+            await writeFile(join(staging, CONFIG_FILE), CONFIG_TEMPLATE, { mode: 0o600 });
+            await writeFile(join(staging, EXAMPLE), CONFIG_EXAMPLE);
             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');
+            await writeFile(join(staging, '.gitignore'), ignoreConfig('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 {
@@ -56,7 +71,6 @@ export class Project {
                     await rmdir(target);
                 }
                 catch (cleanup) {
-                    // [AI:수정] 초기화 실패 오류 보존 코드의 포맷을 맞춘다.
                     throw new AggregateError([cause, cleanup], 'Initialization and destination cleanup failed');
                 }
                 throw cause;
@@ -67,123 +81,635 @@ export class Project {
             await rm(staging, { recursive: true, force: true });
         }
     }
-    async add(root, spec, dryRun = false) {
-        return this.change(root, { add: packageSpec(spec, root) }, dryRun);
+    async migrate(root, dryRun = false) {
+        root = await realpath(root);
+        await readFile(await securePath(root, '.dokebi/state.json'));
+        const tx = await Transaction.begin(root);
+        try {
+            for (const path of [CONFIG_FILE, CONFIG_BACKUP, EXAMPLE])
+                await tx.capture(path);
+            if (await exists(await securePath(root, CONFIG_FILE)))
+                throw new CliError('CONFIG_CONFLICT', 'dokebi.yaml already exists; no configuration files were merged');
+            if (await exists(await securePath(root, CONFIG_BACKUP)))
+                throw new CliError('BACKUP_EXISTS', 'Preserve the existing legacy configuration backup before migrating');
+            const state = readState(parseObject(await tx.read('.dokebi/state.json'), 'state'));
+            if (hash(await tx.read(GENERATED)) !== state.generatedHash)
+                throw new CliError('MODIFIED_REGISTRATION', GENERATED);
+            const main = await tx.read('src/main.ts');
+            if (main !== LEGACY_MAIN_SOURCE && main !== MAIN_SOURCE_V1 && main !== MAIN_SOURCE)
+                throw new CliError('MIGRATION_MAIN_REQUIRED', 'Automatic migration supports generated entry points only; migrate custom src/main.ts and configuration manually using the documented flow');
+            const original = await tx.read(LEGACY_CONFIG_FILE);
+            const source = migrateConfig(original);
+            const config = parseProjectConfig(source);
+            const version = await this.coreVersion(root);
+            const required = await readRequiredPlugins(root);
+            await validatePluginOptions(root, orderPlugins(state.plugins, version, required), config.options);
+            await tx.write(CONFIG_BACKUP, original);
+            await tx.replace(LEGACY_CONFIG_FILE);
+            await this.writeConfiguration(tx, state, source);
+            if (main === LEGACY_MAIN_SOURCE)
+                await tx.write('src/main.ts', MAIN_SOURCE);
+            if (!(await exists(await securePath(root, EXAMPLE))))
+                await tx.write(EXAMPLE, CONFIG_EXAMPLE);
+            const ignorePath = await securePath(root, '.gitignore');
+            const ignore = (await exists(ignorePath)) ? await tx.read('.gitignore') : '';
+            await tx.write('.gitignore', ignoreConfig(ignore));
+            const result = { changed: tx.paths, preserved: [CONFIG_BACKUP] };
+            if (!dryRun)
+                await tx.commit();
+            return result;
+        }
+        finally {
+            await tx.close();
+        }
+    }
+    async add(root, spec, dryRun = false, sets = []) {
+        const operation = packageSpec(spec, root);
+        const session = await this.#begin(root);
+        const { tx, state } = session;
+        try {
+            const dependencies = dependencyMap(session.pkg);
+            const staging = await this.#stage(session, session.pkg, dependencies, operation);
+            const after = await this.#installedDependencies(staging);
+            const name = operation.startsWith('file:')
+                ? Object.keys(after).find((key) => after[key] === operation)
+                : /^(@[^/]+\/[^@]+|[^@]+)/.exec(operation)?.[1];
+            if (!name || !Object.hasOwn(after, name))
+                throw new CliError('INVALID_PACKAGE', 'Cannot identify installed package');
+            const added = await this.#readPackageManifest(staging, name);
+            if (session.required.some((plugin) => plugin.id === added.id || plugin.packageName === added.packageName))
+                throw new CliError('REQUIRED_PLUGIN', 'Core already supplies this required plugin');
+            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', `Use dokebi upgrade ${added.id}`);
+            }
+            if (Object.hasOwn(dependencies, name))
+                throw new CliError('PACKAGE_CONFLICT', name);
+            // Required dependencies that name their npm package are installed in the same staging
+            // and transaction, before the requested plugin (D-0030 §9).
+            const automatic = await this.#automaticDependencies(staging, state, session, added, dependencies);
+            const installed = await this.#installedDependencies(staging);
+            await this.#verifyManifests(staging, state.plugins);
+            const ordered = await this.#order(staging, [...state.plugins, ...automatic, added], session.required);
+            const warnings = setWarnings(sets);
+            let configSource = sets.length
+                ? applySetOptions(session.configSource, added.id, sets)
+                : session.configSource;
+            let config = parseProjectConfig(configSource);
+            const projectPackages = Object.keys(installed);
+            const validator = new PluginOptionsValidator({ allErrors: true });
+            const installations = { ...state.installations };
+            const newIds = new Set([...automatic, added].map((plugin) => plugin.id));
+            const examples = [];
+            // Plans run in dependency order so each plugin sees the ones it builds on.
+            for (const plugin of ordered.filter((item) => newIds.has(item.id))) {
+                const plan = await planLifecycle({
+                    base: staging,
+                    plugin,
+                    options: config.options,
+                    plugins: ordered,
+                    projectPackages,
+                }, 'planInstall');
+                for (const defaults of plan.defaults)
+                    configSource = mergeInstallDefaults(configSource, plugin.id, defaults);
+                config = parseProjectConfig(configSource);
+                const initial = await validator.check(staging, plugin, optionsOf(config.options, plugin.id));
+                configSource = scaffoldConfig(configSource, plugin.id, initial.schema);
+                config = parseProjectConfig(configSource);
+                installations[plugin.id] = {
+                    requires: plan.requires,
+                    directories: plan.directories ?? [],
+                    ...(plan.entry ? { entry: plan.entry.target } : {}),
+                };
+                for (const directory of plan.directories ?? [])
+                    await tx.ensureDirectory(directory);
+                await this.#addFiles(tx, staging, state, plugin, this.#planFiles(plan));
+                examples.push({
+                    id: plugin.id,
+                    update: { defaults: plan.defaults, schema: initial.schema },
+                });
+            }
+            // The first app comes with the plugin, so a new multi-app project runs right away.
+            if (added.id === 'dokebi-app' && !(state.apps ?? []).length) {
+                const first = await this.#addApp(tx, staging, state, configSource, 'main', {
+                    domains: ['localhost'],
+                });
+                configSource = first.configSource;
+                config = parseProjectConfig(configSource);
+                examples.push({ id: 'dokebi-app', update: { changes: first.changes } });
+            }
+            await this.#syncExamples(tx, session.root, warnings, examples);
+            const configRequired = [];
+            await this.#check(staging, ordered, config, installations, projectPackages, { id: added.id, requires: installations[added.id]?.requires ?? [] }, configRequired, warnings);
+            await this.#validateOptions(validator, staging, ordered, config, configRequired);
+            state.plugins = ordered;
+            state.installations = installations;
+            await this.writeConfiguration(tx, state, configSource);
+            await this.#replacePackages(session, staging, session.pkg);
+            const result = {
+                changed: tx.paths,
+                preserved: [],
+                ...(configRequired.length ? { configRequired } : {}),
+                ...(automatic.length
+                    ? {
+                        autoInstalled: automatic.map(({ id, packageName, version }) => ({
+                            id,
+                            packageName,
+                            version,
+                        })),
+                    }
+                    : {}),
+                ...(warnings.length ? { warnings } : {}),
+            };
+            return await this.#finish(session, result, dryRun);
+        }
+        finally {
+            await tx.close();
+        }
+    }
+    /**
+     * Installs, into the staging directory, every missing required dependency (recursively) whose
+     * manifest entry names an npm `package`. Returns their manifests; optional ones are skipped and
+     * required ones without `package` are left to the usual MISSING_REQUIRED_PLUGIN check.
+     */
+    async #automaticDependencies(staging, state, session, added, dependencies) {
+        const known = new Set([
+            ...state.plugins.map((plugin) => plugin.id),
+            ...session.required.map((plugin) => plugin.id),
+            added.id,
+        ]);
+        const result = [];
+        const pending = [added];
+        while (pending.length) {
+            const plugin = pending.shift();
+            for (const dependency of plugin.dependencies) {
+                if (dependency.optional || !dependency.package || known.has(dependency.name))
+                    continue;
+                if (result.length >= 16)
+                    throw new CliError('INVALID_MANIFEST', 'Too many automatic dependencies');
+                if (Object.hasOwn(dependencies, dependency.package))
+                    throw new CliError('PACKAGE_CONFLICT', dependency.package);
+                await this.#stageInstall(session, staging, `${dependency.package}@${dependency.version}`);
+                const manifest = await this.#readPackageManifest(staging, dependency.package);
+                if (manifest.id !== dependency.name)
+                    throw new CliError('INVALID_MANIFEST', `${dependency.package} is not ${dependency.name}`);
+                known.add(manifest.id);
+                result.push(manifest);
+                pending.push(manifest);
+            }
+        }
+        return result;
     }
     async remove(root, id, dryRun = false) {
-        return this.change(root, { remove: id }, dryRun);
+        const session = await this.#begin(root);
+        const { tx, state } = session;
+        try {
+            if (id === 'dokebi-app' && (state.apps ?? []).length)
+                throw new CliError('APPS_PRESENT', 'Remove the apps first (dokebi app remove <name>)', {
+                    details: { apps: state.apps },
+                });
+            if (id === 'dokebi-module' && (state.modules ?? []).length)
+                throw new CliError('MODULES_PRESENT', 'Remove the modules first (dokebi module remove <name>)', { details: { modules: state.modules } });
+            if (session.required.some((plugin) => plugin.id === id || plugin.packageName === id))
+                throw new CliError('REQUIRED_PLUGIN', 'Core-required plugins cannot be removed');
+            const removed = state.plugins.find((plugin) => plugin.id === id);
+            if (!removed)
+                return { changed: [], preserved: [] };
+            if (state.plugins.some((plugin) => plugin.dependencies.some((dep) => dep.name === removed.id && !dep.optional)))
+                throw new CliError('REVERSE_DEPENDENCY', removed.id);
+            const dependencies = dependencyMap(session.pkg);
+            delete dependencies[removed.packageName];
+            const staging = await this.#stage(session, session.pkg, dependencies, undefined);
+            const after = await this.#installedDependencies(staging);
+            const next = state.plugins.filter((plugin) => plugin.id !== removed.id);
+            await this.#verifyManifests(staging, next);
+            const ordered = await this.#order(staging, next, session.required);
+            let configSource = session.configSource;
+            const config = parseProjectConfig(configSource);
+            const installations = { ...state.installations };
+            delete installations[removed.id];
+            const checks = await this.#runChecks(staging, ordered, config, installations, Object.keys(after));
+            for (const plugin of ordered) {
+                if (checks.get(plugin.id)?.requires.includes(removed.id))
+                    throw new CliError('REVERSE_DEPENDENCY', removed.id, {
+                        details: { plugin: plugin.id, requires: [removed.id] },
+                    });
+            }
+            for (const plugin of ordered)
+                installations[plugin.id] = {
+                    ...(installations[plugin.id] ?? defaultInstallation(plugin)),
+                    requires: checks.get(plugin.id)?.requires ?? [],
+                };
+            const validator = new PluginOptionsValidator({ allErrors: true });
+            // Remaining plugins that only miss required values do not block removal; they are
+            // reported in the result like add/upgrade do.
+            const configRequired = [];
+            await this.#validateOptions(validator, staging, ordered, config, configRequired);
+            const preserved = [];
+            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(session.root, path));
+                if (current === file.hash)
+                    await tx.replace(path);
+                else if (current !== null)
+                    preserved.push(path);
+                delete state.files[path];
+            }
+            const marked = markRemoved(configSource, removed.id);
+            configSource = marked.source;
+            if (marked.marked)
+                preserved.push(`${CONFIG_FILE}#options.${removed.id}`);
+            for (const directory of state.installations[removed.id]?.directories ?? []) {
+                if (await exists(await securePath(session.root, directory)))
+                    preserved.push(directory);
+            }
+            if (await exists(await securePath(session.root, EXAMPLE))) {
+                const example = await tx.read(EXAMPLE);
+                try {
+                    const updated = markExampleRemoved(example, removed.id);
+                    if (updated !== example)
+                        await tx.write(EXAMPLE, updated);
+                }
+                catch {
+                    /* An invalid example file is reported by doctor, not by remove. */
+                }
+            }
+            state.plugins = ordered;
+            state.installations = installations;
+            await this.writeConfiguration(tx, state, configSource);
+            await this.#replacePackages(session, staging, session.pkg);
+            const result = {
+                changed: tx.paths,
+                preserved,
+                ...(configRequired.length ? { configRequired } : {}),
+            };
+            return await this.#finish(session, result, dryRun);
+        }
+        finally {
+            await tx.close();
+        }
+    }
+    async upgrade(root, id, to, dryRun = false) {
+        const session = await this.#begin(root);
+        const { tx, state } = session;
+        try {
+            const current = state.plugins.find((plugin) => plugin.id === id);
+            if (!current)
+                throw new CliError('UNKNOWN_PLUGIN', id);
+            // A bare version or range applies to the installed package; otherwise use a full spec.
+            const operation = to === undefined
+                ? `${current.packageName}@latest`
+                : to !== 'latest' && !to.endsWith('.tgz') && validRange(to) !== null
+                    ? packageSpec(`${current.packageName}@${to}`, session.root)
+                    : packageSpec(to, session.root);
+            const dependencies = dependencyMap(session.pkg);
+            const staging = await this.#stage(session, session.pkg, dependencies, operation);
+            const after = await this.#installedDependencies(staging);
+            if (operation.startsWith('file:') &&
+                Object.keys(after).find((key) => after[key] === operation) !== current.packageName)
+                throw new CliError('UPGRADE_IDENTITY_CHANGED', id);
+            if (!operation.startsWith('file:') && !operation.startsWith(current.packageName + '@'))
+                throw new CliError('UPGRADE_IDENTITY_CHANGED', id);
+            const upgraded = await this.#readPackageManifest(staging, current.packageName);
+            if (upgraded.id !== current.id || upgraded.packageName !== current.packageName)
+                throw new CliError('UPGRADE_IDENTITY_CHANGED', id);
+            if (lt(upgraded.version, current.version))
+                throw new CliError('UPGRADE_DOWNGRADE', id);
+            // Same version and same manifest: nothing to do. Same version with a different manifest
+            // (a package changed without a version bump) is applied again so the project can follow
+            // what is installed (D-0037).
+            const sameVersion = upgraded.version === current.version;
+            if (sameVersion && json(upgraded) === json(current))
+                return { changed: [], preserved: [], from: current.version, to: upgraded.version };
+            const others = state.plugins.filter((plugin) => plugin.id !== id);
+            await this.#verifyManifests(staging, others);
+            const ordered = await this.#order(staging, state.plugins.map((plugin) => (plugin.id === id ? upgraded : plugin)), session.required);
+            const installation = state.installations[id] ?? defaultInstallation(current);
+            let configSource = session.configSource;
+            let config = parseProjectConfig(configSource);
+            const projectPackages = Object.keys(after);
+            const plan = await planLifecycle({
+                base: staging,
+                plugin: upgraded,
+                options: config.options,
+                plugins: ordered,
+                projectPackages,
+                installation,
+            }, 'planUpgrade', {
+                from: current.version,
+                to: upgraded.version,
+                installation: installation.entry ? { entry: installation.entry } : {},
+            });
+            if (plan.entry && installation.entry && plan.entry.target !== installation.entry)
+                throw new CliError('UPGRADE_ENTRY_MOVED', id);
+            configSource = applyConfigChanges(configSource, id, plan.configChanges);
+            for (const defaults of plan.defaults)
+                configSource = mergeInstallDefaults(configSource, id, defaults);
+            config = parseProjectConfig(configSource);
+            const validator = new PluginOptionsValidator({ allErrors: true });
+            const initial = await validator.check(staging, upgraded, optionsOf(config.options, id));
+            configSource = scaffoldConfig(configSource, id, initial.schema);
+            config = parseProjectConfig(configSource);
+            const installations = {
+                ...state.installations,
+                [id]: {
+                    requires: plan.requires,
+                    directories: union(installation.directories, plan.directories ?? []),
+                    ...(plan.entry ? { entry: plan.entry.target } : {}),
+                },
+            };
+            const warnings = [];
+            const configRequired = [];
+            await this.#check(staging, ordered, config, installations, projectPackages, { id, requires: plan.requires }, configRequired, warnings);
+            await this.#validateOptions(validator, staging, ordered, config, configRequired);
+            for (const directory of plan.directories ?? [])
+                await tx.ensureDirectory(directory);
+            const details = await this.#reconcileFiles(tx, staging, state, upgraded, this.#planFiles(plan));
+            await this.#syncExample(tx, session.root, id, warnings, {
+                changes: plan.configChanges,
+                defaults: plan.defaults,
+                schema: initial.schema,
+            });
+            state.plugins = ordered;
+            state.installations = installations;
+            await this.writeConfiguration(tx, state, configSource);
+            await this.#replacePackages(session, staging, session.pkg);
+            const result = {
+                changed: tx.paths,
+                preserved: details.map((detail) => detail.path),
+                ...(details.length ? { preservedDetails: details } : {}),
+                ...(configRequired.length ? { configRequired } : {}),
+                ...(warnings.length ? { warnings } : {}),
+                ...(sameVersion ? { reason: 'MANIFEST_CHANGED' } : {}),
+                from: current.version,
+                to: upgraded.version,
+            };
+            return await this.#finish(session, result, dryRun);
+        }
+        finally {
+            await tx.close();
+        }
     }
     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');
+        const pkg = parseObject(await readFile(await packageFile(root, '@dokebi/core', 'package.json'), 'utf8'), 'core');
+        if (pkg.name !== '@dokebi/core' ||
+            typeof pkg.version !== 'string' ||
+            !satisfies(pkg.version, '>=0.2.0'))
+            throw new CliError('CORE_UPGRADE_REQUIRED', 'Dokebi YAML projects require @dokebi/core 0.2.0 or newer');
         return pkg.version;
     }
-    async change(root, operation, dryRun) {
+    /** Takes the project lock and reads the common state every mutation needs. */
+    async #begin(root) {
         root = await realpath(root);
         // Do not create control files in arbitrary non-Dokebi projects.
         await readFile(await securePath(root, '.dokebi/state.json'));
+        const workspaceRoot = await workspaceRootOf(root);
         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')));
+            await tx.capture(LEGACY_CONFIG_FILE);
+            if (await exists(await securePath(root, LEGACY_CONFIG_FILE))) {
+                throw new CliError((await exists(await securePath(root, CONFIG_FILE)))
+                    ? 'CONFIG_CONFLICT'
+                    : 'MIGRATION_REQUIRED', 'Run dokebi migrate after resolving conflicting configuration files');
+            }
+            const configSource = await tx.read(CONFIG_FILE);
+            parseProjectConfig(configSource);
+            const required = await readRequiredPlugins(root);
             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 (!workspaceRoot)
+                return { root, tx, state, configSource, required, pkg };
+            const workspace = {
+                root: workspaceRoot,
+                packages: await workspacePackages(workspaceRoot),
+                lock: await readOptional(join(workspaceRoot, 'package-lock.json')),
+            };
+            return { root, tx, state, configSource, required, pkg, workspace };
+        }
+        catch (error) {
+            await tx.close();
+            throw error;
+        }
+    }
+    async #stage(session, pkg, dependencies, spec) {
+        const { tx, workspace } = session;
+        const staging = join(tx.directory, 'npm');
+        await mkdir(staging);
+        if (!workspace) {
+            await writeFile(join(staging, 'package.json'), json({ ...pkg, dependencies }));
+            const lock = await securePath(tx.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];
+            await this.npm.install(staging, spec);
+            return staging;
+        }
+        // A standalone copy of the member. Workspace packages (maybe unpublished) come in as packed
+        // copies, directly and through overrides, so staging holds no links (D-0035 §3).
+        const names = [
+            ...Object.keys(dependencies),
+            ...DEPENDENCY_SECTIONS.slice(1).flatMap((section) => Object.keys(object(pkg[section] ?? {}, section))),
+        ];
+        const packs = await this.#packWorkspace(session, names);
+        const local = (section) => Object.fromEntries(Object.entries(section).map(([name, value]) => [name, packs.get(name) ?? value]));
+        const staged = { ...pkg, dependencies: local(dependencies) };
+        for (const section of DEPENDENCY_SECTIONS.slice(1))
+            if (pkg[section] !== undefined)
+                staged[section] = local(object(pkg[section], section));
+        staged.overrides = {
+            ...(pkg.overrides && typeof pkg.overrides === 'object' ? pkg.overrides : {}),
+            ...Object.fromEntries(packs),
+        };
+        await writeFile(join(staging, 'package.json'), json(staged));
+        await this.#stageInstall(session, staging, spec);
+        return staging;
+    }
+    /**
+     * Installs `spec` into staging. In a workspace member a workspace package is written into the
+     * staged package.json with the same archive its override names (npm refuses an override that
+     * differs from the direct dependency) and installed from there (D-0035 §3).
+     */
+    async #stageInstall(session, staging, spec) {
+        const workspace = session.workspace;
+        const local = workspace && spec !== undefined && this.#workspacePackage(workspace, spec);
+        if (!local)
+            return this.npm.install(staging, spec);
+        const packs = await this.#packWorkspace(session, [local.name]);
+        const path = join(staging, 'package.json');
+        const staged = parseObject(await readFile(path, 'utf8'), 'staged');
+        staged.dependencies = {
+            ...object(staged.dependencies ?? {}, 'dependencies'),
+            [local.name]: packs.get(local.name),
+        };
+        staged.overrides = {
+            ...object(staged.overrides ?? {}, 'overrides'),
+            ...Object.fromEntries(packs),
+        };
+        await writeFile(path, json(staged));
+        await this.npm.install(staging);
+    }
+    /**
+     * `file:` archives of the named workspace packages and every workspace package they depend on
+     * (dependencies, peers, optional), packed once per operation into the transaction directory.
+     * npm installs a packed archive like a published package; directory overrides with
+     * `--install-links` put the wrong package in place (npm 11, observed with @dokebi/config).
+     */
+    async #packWorkspace(session, names) {
+        const workspace = session.workspace;
+        workspace.packed ??= new Map();
+        const packed = workspace.packed;
+        const pending = [...names];
+        const wanted = [];
+        const seen = new Set(packed.keys());
+        while (pending.length) {
+            const name = pending.pop();
+            const found = workspace.packages.get(name);
+            if (!found || seen.has(name))
+                continue;
+            seen.add(name);
+            wanted.push(name);
+            const manifest = parseObject(await readFile(join(found.directory, 'package.json'), 'utf8'), name);
+            for (const section of ['dependencies', 'peerDependencies', 'optionalDependencies'])
+                pending.push(...Object.keys(object(manifest[section] ?? {}, section)));
+        }
+        const destination = join(session.tx.directory, 'packs');
+        await mkdir(destination, { recursive: true });
+        for (const name of wanted) {
+            const found = workspace.packages.get(name);
+            packed.set(name, `file:${await this.npm.pack(found.directory, destination)}`);
+        }
+        return packed;
+    }
+    /** A registry spec naming a workspace package: that package's folder (D-0035 §3). */
+    #workspacePackage(workspace, spec) {
+        if (spec.startsWith('file:'))
+            return undefined;
+        const match = /^(@[^/@]+\/[^@]+|[^@]+)(?:@(.+))?$/.exec(spec);
+        const found = match?.[1] ? workspace.packages.get(match[1]) : undefined;
+        if (!match?.[1] || !found)
+            return undefined;
+        const range = match[2];
+        if (range !== undefined && range !== 'latest' && !satisfies(found.version, range))
+            throw new CliError('WORKSPACE_VERSION_MISMATCH', `${match[1]} is ${found.version} in the workspace`, { details: { package: match[1], workspace: found.version, requested: range } });
+        return { name: match[1], spec: `file:${found.directory}` };
+    }
+    async #installedDependencies(staging) {
+        return dependencyMap(parseObject(await readFile(join(staging, 'package.json'), 'utf8'), 'installed package'));
+    }
+    async #readPackageManifest(staging, name) {
+        return readManifest(parseObject(await readFile(await packageFile(staging, name, 'package.json'), 'utf8'), name));
+    }
+    /** npm must not silently alter the identity or version of already registered plugins. */
+    async #verifyManifests(staging, plugins) {
+        for (const plugin of plugins) {
+            const actual = await this.#readPackageManifest(staging, plugin.packageName);
+            if (json(actual) !== json(plugin))
+                throw new CliError('MANIFEST_CHANGED', plugin.id);
+        }
+    }
+    async #order(staging, plugins, required) {
+        const stagedRequired = await readRequiredPlugins(staging);
+        if (json(stagedRequired) !== json(required))
+            throw new CliError('MANIFEST_CHANGED', 'Core-required plugins changed during dependency installation');
+        return orderPlugins(plugins, await this.coreVersion(staging), stagedRequired);
+    }
+    #runChecks(base, ordered, config, installations, projectPackages) {
+        return checkAll(ordered.map((plugin) => ({
+            base,
+            plugin,
+            options: config.options,
+            projectPackages,
+            ...(installations[plugin.id] ? { installation: installations[plugin.id] } : {}),
+        })), ordered);
+    }
+    /**
+     * Runs every plugin check after a change. Unsatisfied requirements and error diagnostics stop
+     * the change, except that plugins may report only missing configuration (CONFIG_REQUIRED).
+     */
+    async #check(base, ordered, config, installations, projectPackages, target, configRequired, warnings) {
+        const checks = await this.#runChecks(base, ordered, config, installations, projectPackages);
+        const installed = new Set(ordered.map((plugin) => plugin.id));
+        for (const plugin of ordered) {
+            const result = checks.get(plugin.id) ?? { requires: [], diagnostics: [] };
+            const requires = plugin.id === target.id ? union(target.requires, result.requires) : result.requires;
+            const missing = requires.filter((id) => !installed.has(id));
+            if (missing.length)
+                throw new CliError('MISSING_REQUIRED_PLUGIN', plugin.id, {
+                    details: { plugin: plugin.id, requires: missing },
+                });
+            installations[plugin.id] = {
+                ...(installations[plugin.id] ?? defaultInstallation(plugin)),
+                requires,
+            };
+            const errors = result.diagnostics.filter((item) => item.severity === 'error');
+            for (const item of result.diagnostics)
+                if (item.severity === 'warning')
+                    warnings.push({
+                        code: item.code,
+                        plugin: plugin.id,
+                        ...(item.optionPath ? { path: item.optionPath.join('.') } : {}),
+                    });
+            if (!errors.length)
+                continue;
+            if (errors.every((item) => item.code === 'CONFIG_REQUIRED')) {
+                configRequired.push({
+                    plugin: plugin.id,
+                    errors: errors.slice(0, 20).map((item) => ({
+                        instancePath: '/' + (item.optionPath ?? []).join('/'),
+                        keyword: 'required',
+                    })),
+                    errorCount: errors.length,
+                });
+                continue;
             }
-            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;
+            throw new CliError('PLUGIN_CHECK_FAILED', plugin.id, {
+                details: { plugin: plugin.id, diagnostics: errors.slice(0, 20) },
+            });
         }
-        finally {
-            await tx.close();
+    }
+    async #validateOptions(validator, staging, ordered, config, configRequired) {
+        for (const plugin of ordered) {
+            const checked = await validator.check(staging, plugin, optionsOf(config.options, plugin.id));
+            if (!checked.errors.length)
+                continue;
+            // Only missing required values (this plugin or one installed earlier) do not block the
+            // change; they are reported together so the developer can fill them in later.
+            if (checked.errors.every((error) => error.keyword === 'required')) {
+                configRequired.push({
+                    plugin: plugin.id,
+                    errors: checked.errors.slice(0, 20),
+                    errorCount: checked.errors.length,
+                });
+            }
+            else {
+                throw new CliError('INVALID_PLUGIN_OPTIONS', plugin.id, {
+                    details: {
+                        plugin: plugin.id,
+                        errors: checked.errors.slice(0, 20),
+                        errorCount: checked.errors.length,
+                    },
+                });
+            }
         }
     }
-    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);
+    #planFiles(plan) {
+        return plan.entry ? [...plan.files, plan.entry] : plan.files;
+    }
+    async #addFiles(tx, staging, state, plugin, files) {
+        for (const file of files) {
+            const content = await readFile(await packageFile(staging, plugin.packageName, file.source));
             const digest = hash(content);
             await tx.capture(file.target);
             const current = await fingerprint(await securePath(tx.root, file.target));
@@ -201,11 +727,537 @@ export class Project {
             }
         }
     }
-    async writeConfiguration(tx, state, config) {
-        const generated = generateRegistration(state.plugins);
+    /** Applies a new template set while preserving files the user changed or deleted. */
+    async #reconcileFiles(tx, staging, state, plugin, files) {
+        const planned = new Map(files.map((file) => [file.target, file.source]));
+        const details = [];
+        for (const [path, owned] of Object.entries(state.files)) {
+            if (!owned.owners.includes(plugin.id))
+                continue;
+            const source = planned.get(path);
+            planned.delete(path);
+            await tx.capture(path);
+            const current = await fingerprint(await securePath(tx.root, path));
+            const update = source === undefined ? undefined : 'node_modules/' + plugin.packageName + '/' + source;
+            if (current === null) {
+                owned.owners = owned.owners.filter((owner) => owner !== plugin.id);
+                if (!owned.owners.length)
+                    delete state.files[path];
+                details.push({ path, reason: 'DELETED' });
+                continue;
+            }
+            if (current !== owned.hash) {
+                details.push({ path, reason: 'MODIFIED', ...(update ? { update } : {}) });
+                continue;
+            }
+            if (owned.owners.length > 1) {
+                if (source === undefined)
+                    owned.owners = owned.owners.filter((owner) => owner !== plugin.id);
+                else
+                    details.push({ path, reason: 'SHARED', ...(update ? { update } : {}) });
+                continue;
+            }
+            if (source === undefined) {
+                await tx.replace(path);
+                delete state.files[path];
+                continue;
+            }
+            const content = await readFile(await installedPath(staging, update));
+            const digest = hash(content);
+            if (digest !== owned.hash) {
+                await tx.write(path, content);
+                owned.hash = digest;
+            }
+        }
+        await this.#addFiles(tx, staging, state, plugin, [...planned].map(([target, source]) => ({ source, target })));
+        return details;
+    }
+    async #syncExample(tx, root, id, warnings, update) {
+        await this.#syncExamples(tx, root, warnings, [{ id, update }]);
+    }
+    /** Applies several plugin updates to dokebi.example.yaml and writes it once. */
+    async #syncExamples(tx, root, warnings, updates) {
+        if (!(await exists(await securePath(root, EXAMPLE)))) {
+            warnings.push({ code: 'EXAMPLE_MISSING', path: EXAMPLE });
+            return;
+        }
+        const source = await tx.read(EXAMPLE);
+        let next = source;
+        try {
+            for (const { id, update } of updates)
+                next = syncExample(next, id, update);
+        }
+        catch {
+            warnings.push({ code: 'EXAMPLE_INVALID', path: EXAMPLE });
+            return;
+        }
+        if (next !== source)
+            await tx.write(EXAMPLE, next);
+    }
+    async #replacePackages(session, staging, pkg) {
+        const { tx, workspace } = session;
+        if (!workspace) {
+            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'));
+            return;
+        }
+        // Only the member's package.json changes here; the workspace root's npm install brings the
+        // lock and node_modules in line after the project files are in (D-0035 §4).
+        const staged = parseObject(await readFile(join(staging, 'package.json'), 'utf8'), 'staged');
+        const next = structuredClone(pkg);
+        for (const section of DEPENDENCY_SECTIONS) {
+            if (staged[section] === undefined) {
+                delete next[section];
+                continue;
+            }
+            // A workspace package keeps the member's own range while the workspace version meets it;
+            // otherwise (new or upgraded) it gets that exact version. npm keeps the lists sorted.
+            const before = object(pkg[section] ?? {}, section);
+            next[section] = Object.fromEntries(Object.entries(object(staged[section], section))
+                .map(([name, value]) => {
+                const found = workspace.packages.get(name);
+                if (!found || !String(value).startsWith('file:'))
+                    return [name, value];
+                const range = before[name];
+                return [
+                    name,
+                    typeof range === 'string' && satisfies(found.version, range) ? range : found.version,
+                ];
+            })
+                .sort(([a], [b]) => String(a).localeCompare(String(b))));
+        }
+        await tx.write('package.json', json(next));
+        workspace.install = { core: await this.coreVersion(staging) };
+    }
+    /** Commits the project files; a workspace member then runs npm install at the root. */
+    async #finish(session, result, dryRun = false) {
+        const workspace = session.workspace;
+        if (workspace?.install)
+            result.workspaceInstall = workspace.root;
+        if (dryRun)
+            return result;
+        if (!workspace?.install) {
+            await session.tx.commit();
+            return result;
+        }
+        const lockPath = join(workspace.root, 'package-lock.json');
+        let failure;
+        let installed = false;
+        try {
+            await session.tx.commit(undefined, async () => {
+                try {
+                    if ((await readOptional(lockPath)) !== workspace.lock)
+                        throw new CliError('CONCURRENT_CHANGE', 'Workspace package-lock.json changed');
+                    installed = true;
+                    await this.npm.installWorkspace(workspace.root);
+                    // What npm put in the workspace must be what was checked in staging.
+                    await this.#verifyManifests(session.root, session.state.plugins);
+                    if ((await this.coreVersion(session.root)) !== workspace.install?.core)
+                        throw new CliError('MANIFEST_CHANGED', '@dokebi/core');
+                }
+                catch (error) {
+                    failure = error;
+                    throw error;
+                }
+            });
+        }
+        catch (error) {
+            if (failure === undefined || !installed)
+                throw failure ?? error;
+            // The project files are back (or RECOVERY_REQUIRED); bring the root back to its lock.
+            try {
+                if (workspace.lock === null)
+                    await rm(lockPath, { force: true });
+                else
+                    await writeFile(lockPath, workspace.lock);
+                await this.npm.installWorkspace(workspace.root);
+            }
+            catch (cause) {
+                throw new CliError('WORKSPACE_SYNC_FAILED', 'Project files were rolled back; run npm install at the workspace root', {
+                    cause: new AggregateError([failure, cause]),
+                    details: { workspaceRoot: workspace.root },
+                });
+            }
+            throw error instanceof CliError && error.code === 'RECOVERY_REQUIRED' ? error : failure;
+        }
+        return result;
+    }
+    /**
+     * `dokebi app add <name>`: copies the app skeleton of @dokebi/app to src/apps/<name>, maps the
+     * given domains to it in dokebi.yaml and registers it in the generated code (D-0030 §7).
+     */
+    async appAdd(root, name, options = {}) {
+        const session = await this.#begin(root);
+        const { tx, state } = session;
+        try {
+            this.#requireAppPlugin(state);
+            const added = await this.#addApp(tx, session.root, state, session.configSource, name, options);
+            const warnings = [];
+            if (options.inertia &&
+                !state.plugins.some((plugin) => plugin.id === 'dokebi-template-inertia'))
+                warnings.push({ code: 'INERTIA_PLUGIN_MISSING', path: `src/apps/${name}` });
+            if (options.ssr && !options.inertia)
+                throw new CliError('USAGE', 'Server rendering (--ssr) needs --inertia');
+            if (options.inertia)
+                await this.#inertiaBuild(tx, session, warnings, options.ssr === true);
+            // Domains are not secrets: the shared sample keeps them so `setup` scripts see them too.
+            await this.#syncExamples(tx, session.root, warnings, [
+                { id: 'dokebi-app', update: { changes: added.changes } },
+            ]);
+            await this.writeConfiguration(tx, state, parseAndRender(added.configSource));
+            const result = {
+                changed: tx.paths,
+                preserved: [],
+                ...(warnings.length ? { warnings } : {}),
+                ...(options.inertia ? { nextSteps: ['npm run build'] } : {}),
+            };
+            return await this.#finish(session, result, options.dryRun);
+        }
+        finally {
+            await tx.close();
+        }
+    }
+    /** `dokebi app link <app> <domain> [--template t]`: maps one more domain to an existing app. */
+    async appLink(root, name, domain, options = {}) {
+        const session = await this.#begin(root);
+        const { tx, state } = session;
+        try {
+            this.#requireAppPlugin(state);
+            if (!(state.apps ?? []).includes(name))
+                throw new CliError('UNKNOWN_APP', name);
+            const template = options.template ?? 'default';
+            if (!APP_NAME.test(template))
+                throw new CliError('INVALID_APP', 'Template names match ' + APP_NAME.source);
+            if (!HOST.test(domain) || domain.length > 253)
+                throw new CliError('INVALID_APP', 'Domains are lower-case host names without a port');
+            const current = domainTarget(parseProjectConfig(session.configSource).options, domain);
+            if (current && current !== name)
+                throw new CliError('DOMAIN_IN_USE', domain, { details: { domain, app: current } });
+            const views = `src/apps/${name}/views/${template}`;
+            if (template !== 'default' && !(await exists(await securePath(tx.root, views))))
+                await tx.ensureDirectory(views);
+            const changes = domainChanges([domain], template === 'default' ? { app: name } : { app: name, template });
+            const warnings = [];
+            await this.#syncExamples(tx, session.root, warnings, [
+                { id: 'dokebi-app', update: { changes } },
+            ]);
+            await tx.write(CONFIG_FILE, applyConfigChanges(session.configSource, 'dokebi-app', changes));
+            const result = {
+                changed: tx.paths,
+                preserved: [],
+                ...(warnings.length ? { warnings } : {}),
+            };
+            return await this.#finish(session, result, options.dryRun);
+        }
+        finally {
+            await tx.close();
+        }
+    }
+    /** `dokebi app unlink <domain>`: removes one domain mapping from dokebi.yaml and the sample. */
+    async appUnlink(root, domain, dryRun = false) {
+        const session = await this.#begin(root);
+        const { tx, state } = session;
+        try {
+            this.#requireAppPlugin(state);
+            if (!domainTarget(parseProjectConfig(session.configSource).options, domain))
+                throw new CliError('UNKNOWN_DOMAIN', domain);
+            const changes = [{ op: 'remove', path: ['domains', domain] }];
+            const warnings = [];
+            await this.#syncExamples(tx, session.root, warnings, [
+                { id: 'dokebi-app', update: { changes } },
+            ]);
+            await tx.write(CONFIG_FILE, applyConfigChanges(session.configSource, 'dokebi-app', changes));
+            const result = {
+                changed: tx.paths,
+                preserved: [],
+                ...(warnings.length ? { warnings } : {}),
+            };
+            return await this.#finish(session, result, dryRun);
+        }
+        finally {
+            await tx.close();
+        }
+    }
+    /** `dokebi app remove <name>`: unregisters the app; its folder is user code and stays. */
+    async appRemove(root, name, dryRun = false) {
+        const session = await this.#begin(root);
+        const { tx, state } = session;
+        try {
+            this.#requireAppPlugin(state);
+            if (!(state.apps ?? []).includes(name))
+                throw new CliError('UNKNOWN_APP', name);
+            const domains = appDomains(parseProjectConfig(session.configSource).options, name);
+            if (domains.length)
+                throw new CliError('APP_IN_USE', name, { details: { app: name, domains } });
+            state.apps = (state.apps ?? []).filter((app) => app !== name);
+            if (!state.apps.length)
+                delete state.apps;
+            await this.writeConfiguration(tx, state, session.configSource);
+            const result = { changed: tx.paths, preserved: [`src/apps/${name}`] };
+            return await this.#finish(session, result, dryRun);
+        }
+        finally {
+            await tx.close();
+        }
+    }
+    /** `dokebi app list`: apps with the domains and templates that show them. */
+    async appList(root) {
+        const state = readState(parseObject(await readFile(await securePath(root, '.dokebi/state.json'), 'utf8'), 'state'));
+        const config = parseProjectConfig(await readFile(await securePath(root, CONFIG_FILE), 'utf8')).options;
+        return {
+            apps: (state.apps ?? []).map((name) => ({ name, domains: appDomains(config, name) })),
+        };
+    }
+    /**
+     * `dokebi module add <name>` (D-0032): copies the module skeleton of @dokebi/module to
+     * src/shared/modules/<name> and registers it in the generated code. `views: false` copies the
+     * skeleton without views (routes answer JSON).
+     */
+    async moduleAdd(root, name, options = {}) {
+        const session = await this.#begin(root);
+        const { tx, state } = session;
+        try {
+            if (!state.plugins.some((plugin) => plugin.id === 'dokebi-module'))
+                throw new CliError('MODULE_PLUGIN_MISSING', 'Run dokebi add @dokebi/module first');
+            if (!APP_NAME.test(name))
+                throw new CliError('INVALID_MODULE', 'Module names match ' + APP_NAME.source);
+            if ((state.modules ?? []).includes(name))
+                throw new CliError('MODULE_EXISTS', name);
+            const folder = `src/shared/modules/${name}`;
+            templateTarget(folder + '/module.ts');
+            if (await exists(await securePath(tx.root, folder)))
+                throw new CliError('FILE_CONFLICT', folder);
+            const skeleton = options.views === false ? 'module-api' : 'module';
+            const source = await packageFile(session.root, '@dokebi/module', `templates/${skeleton}`);
+            if (!(await exists(source)))
+                throw new CliError('INVALID_MANIFEST', 'Upgrade @dokebi/module (no module skeleton)');
+            for (const file of await listFiles(source)) {
+                const target = `${folder}/${file}`;
+                templateTarget(target);
+                const content = await readFile(join(source, file));
+                await tx.write(target, /\.(?:ts|js|ejs|md|json)$/.test(file)
+                    ? content.toString('utf8').replaceAll('{{module}}', name)
+                    : content);
+            }
+            state.modules = [...(state.modules ?? []), name];
+            await this.writeConfiguration(tx, state, session.configSource);
+            const result = {
+                changed: tx.paths,
+                preserved: [],
+                nextSteps: [
+                    `mount it in an app: modules: { '/${name}': <import of src/shared/modules/${name}/module.ts> }`,
+                ],
+            };
+            return await this.#finish(session, result, options.dryRun);
+        }
+        finally {
+            await tx.close();
+        }
+    }
+    /** `dokebi module remove <name>`: unregisters the module; its folder is user code and stays. */
+    async moduleRemove(root, name, dryRun = false) {
+        const session = await this.#begin(root);
+        const { tx, state } = session;
+        try {
+            if (!(state.modules ?? []).includes(name))
+                throw new CliError('UNKNOWN_MODULE', name);
+            state.modules = (state.modules ?? []).filter((module) => module !== name);
+            if (!state.modules.length)
+                delete state.modules;
+            await this.writeConfiguration(tx, state, session.configSource);
+            const result = {
+                changed: tx.paths,
+                preserved: [`src/shared/modules/${name}`],
+            };
+            return await this.#finish(session, result, dryRun);
+        }
+        finally {
+            await tx.close();
+        }
+    }
+    /** `dokebi module list`: the registered modules in registration order. */
+    async moduleList(root) {
+        const state = readState(parseObject(await readFile(await securePath(root, '.dokebi/state.json'), 'utf8'), 'state'));
+        return {
+            modules: (state.modules ?? []).map((name) => ({
+                name,
+                path: `src/shared/modules/${name}`,
+            })),
+        };
+    }
+    /**
+     * What an Inertia app needs to be built (D-0031 supplement): one project-wide vite.config.ts
+     * that finds every src/apps/<app>/views/app.js, a `build` script, the Vite and Vue packages as
+     * dev dependencies, and dist/ in .gitignore. Existing files, scripts and versions are kept.
+     * With server rendering (D-0039) also vite.ssr.config.ts, and `build` runs both builds.
+     */
+    async #inertiaBuild(tx, session, warnings, ssr) {
+        const source = await packageFile(session.root, '@dokebi/app', 'templates/inertia-build');
+        const build = parseObject(await readFile(join(source, 'build.json'), 'utf8'), 'build.json');
+        const wanted = object(build.devDependencies ?? {}, 'devDependencies');
+        const { build: browserScript, buildSsr: ssrScript } = object(build.scripts ?? {}, 'scripts');
+        const pkg = structuredClone(session.pkg);
+        const scripts = object(pkg.scripts ?? {}, 'scripts');
+        if (typeof browserScript !== 'string' || typeof ssrScript !== 'string')
+            throw new CliError('INVALID_MANIFEST', 'build.json scripts');
+        const script = ssr ? ssrScript : browserScript;
+        // The browser-only script of an earlier `app add --inertia` grows into the SSR one; a script
+        // the developer wrote is kept, and the warning says to add the server build by hand.
+        if (scripts.build === undefined || (ssr && scripts.build === browserScript))
+            scripts.build = script;
+        else if (scripts.build !== script && !(!ssr && scripts.build === ssrScript))
+            warnings.push({ code: 'BUILD_SCRIPT_KEPT', path: 'package.json' });
+        pkg.scripts = scripts;
+        const devDependencies = object(pkg.devDependencies ?? {}, 'devDependencies');
+        const dependencies = dependencyMap(pkg);
+        let install = false;
+        for (const [name, version] of Object.entries(wanted)) {
+            if (!PACKAGE_NAME.test(name) ||
+                typeof version !== 'string' ||
+                !/^\d+\.\d+\.\d+$/.test(version))
+                throw new CliError('INVALID_MANIFEST', 'build.json devDependencies');
+            if (dependencies[name] !== undefined || devDependencies[name] !== undefined)
+                continue;
+            devDependencies[name] = version;
+            install = true;
+        }
+        pkg.devDependencies = Object.fromEntries(Object.entries(devDependencies).sort(([a], [b]) => a.localeCompare(b)));
+        if (install)
+            await this.#replacePackages(session, await this.#stage(session, pkg, dependencies, undefined), pkg);
+        else if (json(pkg) !== json(session.pkg))
+            await tx.write('package.json', json(pkg));
+        const configs = ['vite.config.ts', 'vite.config.mts', 'vite.config.js', 'vite.config.mjs'];
+        let configured = false;
+        for (const file of configs)
+            configured ||= await exists(await securePath(session.root, file));
+        if (!configured)
+            await tx.write('vite.config.ts', await readFile(join(source, 'vite.config.ts'), 'utf8'));
+        if (ssr) {
+            let ssrConfigured = false;
+            for (const file of configs.map((name) => name.replace('vite.config', 'vite.ssr.config')))
+                ssrConfigured ||= await exists(await securePath(session.root, file));
+            if (!ssrConfigured)
+                await tx.write('vite.ssr.config.ts', await readFile(join(source, 'vite.ssr.config.ts'), 'utf8'));
+        }
+        const ignorePath = await securePath(session.root, '.gitignore');
+        const ignore = (await exists(ignorePath)) ? await tx.read('.gitignore') : '';
+        if (!ignore.split(/\r?\n/).some((line) => ['dist', 'dist/', '/dist', '/dist/'].includes(line)))
+            await tx.write('.gitignore', `${ignore}${ignore && !ignore.endsWith('\n') ? '\n' : ''}dist/\n`);
+    }
+    #requireAppPlugin(state) {
+        if (!state.plugins.some((plugin) => plugin.id === 'dokebi-app'))
+            throw new CliError('APP_PLUGIN_MISSING', 'Run dokebi add @dokebi/app first');
+    }
+    /** Shared by `app add` and the first app created with `dokebi add @dokebi/app`. */
+    async #addApp(tx, packagesRoot, state, configSource, name, options) {
+        if (!APP_NAME.test(name))
+            throw new CliError('INVALID_APP', 'App names match ' + APP_NAME.source);
+        const template = options.template ?? 'default';
+        if (!APP_NAME.test(template))
+            throw new CliError('INVALID_APP', 'Template names match ' + APP_NAME.source);
+        if ((state.apps ?? []).includes(name))
+            throw new CliError('APP_EXISTS', name);
+        const folder = `src/apps/${name}`;
+        templateTarget(folder + '/app.ts');
+        if (await exists(await securePath(tx.root, folder)))
+            throw new CliError('FILE_CONFLICT', folder);
+        const domains = [...new Set(options.domains ?? [])];
+        const config = parseProjectConfig(configSource).options;
+        for (const domain of domains) {
+            if (!HOST.test(domain) || domain.length > 253)
+                throw new CliError('INVALID_APP', 'Domains are lower-case host names without a port');
+            const current = domainTarget(config, domain);
+            if (current && current !== name)
+                throw new CliError('DOMAIN_IN_USE', domain, { details: { domain, app: current } });
+        }
+        // Directories first: commit creates them in order, before files create parents themselves.
+        if (template !== 'default')
+            await tx.ensureDirectory(`${folder}/views/${template}`);
+        // EJS or Inertia skeleton; `{{app}}` in text files becomes the app name (paths to its views).
+        // Server rendering lays app-inertia-ssr (views/ssr.js, an app.ts naming the bundle) on top.
+        const skeletons = options.inertia
+            ? ['app-inertia', ...(options.ssr ? ['app-inertia-ssr'] : [])]
+            : ['app'];
+        const files = new Map();
+        for (const skeleton of skeletons) {
+            const source = await packageFile(packagesRoot, '@dokebi/app', `templates/${skeleton}`);
+            for (const file of await listFiles(source))
+                files.set(file, join(source, file));
+        }
+        for (const [file, path] of files) {
+            const target = `${folder}/${file}`;
+            templateTarget(target);
+            const content = await readFile(path);
+            await tx.write(target, /\.(?:ts|js|vue|ejs|md|json)$/.test(file)
+                ? content.toString('utf8').replaceAll('{{app}}', name)
+                : content);
+        }
+        const changes = domainChanges(domains, template === 'default' ? { app: name } : { app: name, template });
+        state.apps = [...(state.apps ?? []), name];
+        return { configSource: applyConfigChanges(configSource, 'dokebi-app', changes), changes };
+    }
+    async writeConfiguration(tx, state, configSource) {
+        const generated = generateRegistration(state.plugins, state.installations, state.apps ?? [], state.modules ?? []);
         state.generatedHash = hash(generated);
         await tx.write(GENERATED, generated);
-        await tx.write('dokebi.json', json(config));
+        await tx.write(CONFIG_FILE, configSource);
         await tx.write('.dokebi/state.json', json(state));
     }
 }
+const HOST = /^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$/;
+function domainsOf(options) {
+    const section = options['dokebi-app'];
+    const domains = section && typeof section === 'object'
+        ? section.domains
+        : undefined;
+    return domains && typeof domains === 'object' ? domains : {};
+}
+function domainTarget(options, domain) {
+    const target = domainsOf(options)[domain];
+    const app = target && typeof target === 'object' ? target.app : undefined;
+    return typeof app === 'string' ? app : undefined;
+}
+function appDomains(options, name) {
+    return Object.entries(domainsOf(options))
+        .filter(([, target]) => target?.app === name)
+        .map(([domain, target]) => ({
+        domain,
+        template: String(target.template ?? 'default'),
+    }));
+}
+/** Relative paths of the regular files below `directory`, in a stable order. */
+async function listFiles(directory, prefix = '') {
+    const result = [];
+    for (const entry of (await readdir(join(directory, prefix), { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+        const path = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory())
+            result.push(...(await listFiles(directory, path)));
+        else if (entry.isFile())
+            result.push(path);
+        else
+            throw new CliError('INVALID_MANIFEST', 'App templates must be regular files');
+    }
+    return result;
+}
+function parseAndRender(source) {
+    parseProjectConfig(source);
+    return source;
+}
+/** Replaces each domain mapping (remove, then set) so a re-link changes app or template. */
+function domainChanges(domains, target) {
+    return domains.flatMap((domain) => [
+        { op: 'remove', path: ['domains', domain] },
+        { op: 'default', path: ['domains', domain], value: target },
+    ]);
+}
+async function readOptional(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}