@dokebi/cli 0.4.1 → 0.4.26

package/dist/project-inspector.js

@@ -1,21 +1,101 @@
-import { readdir, readFile, realpath } from 'node:fs/promises';
+import { readdir, readFile, realpath, stat } from 'node:fs/promises';
+import { join } from 'node:path';
 import satisfies from 'semver/functions/satisfies.js';
 import valid from 'semver/functions/valid.js';
-import { CONFIG_FILE, LEGACY_CONFIG_FILE, parseProjectConfig } from './configuration.js';
+import { CONFIG_FILE, configTarget, FRESH_COPY_FIX, LEGACY_CONFIG_FILE, parseProjectConfig, readProjectConfigSource, } from './configuration.js';
+import { connectionSecrets } from './dev-compose.js';
+import { COMPOSE_FILE, composeAppPortHint, composeBuildsAppHint, composeServicesBuildingProject, composeServicesPublishing, composeUnsetVariables, composeVariablesHint, composeVariablesOf, envKeys, } from './dev-infra.js';
+import { debug, describeError, isMissing } from './diagnostics.js';
+import { ENV_FILE, envFileWarnings } from './env-file.js';
 import { CliError } from './errors.js';
 import { exists, fingerprint, hash, json, parseObject, securePath } from './filesystem.js';
-import { legacyLayout } from './layout.js';
+import { adminSections } from './first-admin.js';
+import { legacyLayout, MOVED_RECIPE_FILES } from './layout.js';
 import { loggingDiagnostics } from './logging-config.js';
-import { orderPlugins, readManifest } from './manifest.js';
+import { optionsKey, orderPlugins, readManifest } from './manifest.js';
 import { dependencyMap, validateProjectPackage } from './npm-client.js';
-import { checkPlugin } from './plugin-lifecycle.js';
+import { optionsFix } from './option-fixes.js';
+import { checkPlugin, checkPluginsOptions } from './plugin-lifecycle.js';
 import { PluginOptionsValidator } from './plugin-options.js';
-import { AGENTS_FILE, guideEntries, INSTALLED_END, INSTALLED_START, installedBlockEdited, } from './project-guide.js';
+import { AGENTS_FILE, guideEntries, INSTALLED_END, INSTALLED_START, installedBlockEdited, PROJECT_END, PROJECT_START, projectBlockState, } from './project-guide.js';
 import { readState } from './project-state.js';
+import { ADMIN_SECTION, LEGACY_ADMIN_SECTION, SEED_FILE } from './recipe-login.js';
 import { readRequiredPlugins } from './required-plugins.js';
+import { CONVENTION_SECTIONS, catalogPackageOf, renderSettingsSchema, settingsFile, settingsSchemaFile, undeclaredSection, } from './settings.js';
+import { templateFixes } from './template-fixes.js';
 import { installedPath } from './workspace.js';
+/**
+ * Reads `.dokebi/lock` (`{ pid }`, written by Transaction.begin) without taking it (AI-M04 F6):
+ * only a signal-0 probe, no `ps`. A reused pid can look alive; `since` lets a reader see an old
+ * lock. Null when the lock is gone.
+ */
+export async function lockHolder(root) {
+    const file = join(root, '.dokebi', 'lock');
+    let pid = null;
+    let since = null;
+    try {
+        since = (await stat(file)).mtime.toISOString();
+        const value = JSON.parse(await readFile(file, 'utf8'));
+        if (Number.isSafeInteger(value?.pid) && value.pid > 0)
+            pid = value.pid;
+    }
+    catch (error) {
+        // Gone since the listing: the command ended. Otherwise written half: no pid known.
+        if (isMissing(error))
+            return null;
+        debug('inspect: lock file without a readable pid', { error: describeError(error) });
+    }
+    if (pid === null)
+        return { pid, running: null, since };
+    let running;
+    try {
+        process.kill(pid, 0);
+        running = true;
+    }
+    catch (error) {
+        const code = error.code;
+        // EPERM: it lives under another user or sandbox; ESRCH: gone; anything else: unknown.
+        running = code === 'EPERM' ? true : code === 'ESRCH' ? false : null;
+        if (running === null)
+            debug('inspect: lock holder probe failed', { pid, error: describeError(error) });
+    }
+    debug('inspect: project lock held', { pid, running, since });
+    return { pid, running, since };
+}
+/** The PROJECT_LOCKED diagnostic with what to do (AI-M04 F6). */
+export function lockDiagnostic(holder, transactions) {
+    const who = holder.pid === null ? 'a dokebi command' : `a dokebi command (pid ${holder.pid})`;
+    return {
+        code: 'PROJECT_LOCKED',
+        severity: 'error',
+        path: '.dokebi/lock',
+        plugin: null,
+        details: { ...holder, transactions },
+        hint: holder.running === true
+            ? `${who} holds the lock and is changing the project right now (a --dry-run takes it too), so this read may show its unfinished work${transactions.length ? ` (${transactions.join(', ')} is its open transaction, not an interrupted one)` : ''}. inspect is read-only and takes no lock: run it again when that command has ended. Never delete the lock`
+            : holder.running === false
+                ? `${who} took the lock and is no longer running: a change was interrupted. Do not delete .dokebi/lock or .dokebi/transaction-* (the backups of the originals); ask the user to look`
+                : `.dokebi/lock names no process. If no dokebi command is running, a change was interrupted: ask the user to look; never delete the lock`,
+    };
+}
 // Reads metadata only and never creates locks. With runChecks (doctor), each plugin's
 // installation module check runs in the permission-restricted child process.
+/**
+ * S-c: fixes of the @dokebi/db adapter templates a copy made earlier may lack: found by a marker
+ * of the fix in the installed template and its absence in the copy.
+ */
+/** The apps under src/apps with an Inertia browser entry (views/app.js), sorted by name. */
+async function inertiaAppNames(root) {
+    const apps = await securePath(root, 'src/apps');
+    if (!(await exists(apps)))
+        return [];
+    const names = [];
+    for (const entry of await readdir(apps, { withFileTypes: true }))
+        if (entry.isDirectory() &&
+            (await exists(await securePath(root, `src/apps/${entry.name}/views/app.js`))))
+            names.push(entry.name);
+    return names.sort();
+}
 export class ProjectInspector {
     async inspect(directory, settings = {}) {
         const root = await realpath(directory);
@@ -29,7 +109,35 @@ export class ProjectInspector {
             diagnostics: [],
         };
         const originals = new Map();
-        const optionsValidator = new PluginOptionsValidator();
+        // M50: the settings file the app reads (DOKEBI_CONFIG, else dokebi.yaml); diagnostics name it.
+        const settingsTarget = await configTarget(root);
+        const configFile = settingsTarget.file;
+        // R4CC-7: a DOKEBI_CONFIG line of .env is never passed to the app (the environment names the
+        // settings file); doctor says so as a warning, as start, dev and verify do.
+        try {
+            for (const warning of envFileWarnings(root))
+                result.diagnostics.push({
+                    code: warning.code,
+                    path: warning.path,
+                    plugin: null,
+                    severity: 'warning',
+                    hint: warning.hint,
+                });
+        }
+        catch (error) {
+            if (!(error instanceof CliError))
+                throw error;
+            result.diagnostics.push({
+                code: error.code,
+                path: ENV_FILE,
+                plugin: null,
+                severity: 'error',
+                ...(error.details !== undefined ? { details: error.details } : {}),
+            });
+        }
+        const composePath = await securePath(root, COMPOSE_FILE);
+        // Every issue (D-0153): the fix names all unknown keys in one config unset.
+        const optionsValidator = new PluginOptionsValidator({ allErrors: true });
         const issue = (code, path, plugin = null, severity = 'error') => {
             result.diagnostics.push({ code, path, plugin, severity });
         };
@@ -57,24 +165,46 @@ export class ProjectInspector {
         };
         const read = async (path) => {
             // node_modules paths resolve like Node in a workspace member (D-0035).
-            const text = await readFile(await installedPath(root, path), 'utf8');
+            const text = path === configFile
+                ? await readProjectConfigSource(root, settingsTarget.path)
+                : await readFile(await installedPath(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(CONFIG_FILE, async () => {
-            if (await exists(await securePath(root, LEGACY_CONFIG_FILE)))
-                throw new CliError((await exists(await securePath(root, CONFIG_FILE)))
-                    ? 'CONFIG_CONFLICT'
-                    : 'MIGRATION_REQUIRED', 'Explicit YAML migration is required');
-            return parseProjectConfig(await read(CONFIG_FILE));
-        });
+        // R3 Claude T4 review: a fresh copy without dokebi.yaml got ENOENT with no fix, and every
+        // plugin's options then read as missing (INVALID_PLUGIN_OPTIONS "correct options.…").
+        const configMissing = !settingsTarget.fromEnvironment &&
+            !(await exists(settingsTarget.path)) &&
+            !(await exists(await securePath(root, LEGACY_CONFIG_FILE)));
+        if (configMissing)
+            result.diagnostics.push({
+                code: 'NOT_A_PROJECT',
+                path: configFile,
+                plugin: null,
+                severity: 'error',
+                details: { file: configFile, fix: FRESH_COPY_FIX },
+                hint: FRESH_COPY_FIX,
+            });
+        const config = configMissing
+            ? null
+            : await check(configFile, async () => {
+                if (await exists(await securePath(root, LEGACY_CONFIG_FILE)))
+                    throw new CliError((await exists(await securePath(root, CONFIG_FILE)))
+                        ? 'CONFIG_CONFLICT'
+                        : 'MIGRATION_REQUIRED', 'Explicit YAML migration is required');
+                return parseProjectConfig(await read(configFile));
+            });
         result.requiredPlugins =
             (await check('node_modules/@dokebi/core/package.json', () => readRequiredPlugins(root))) ??
                 [];
+        let typecheckScript;
         const pkg = await check('package.json', async () => {
             const value = parseObject(await read('package.json'), 'package');
             validateProjectPackage(value);
+            const scripts = value.scripts;
+            if (scripts && typeof scripts === 'object' && !Array.isArray(scripts))
+                typecheckScript = scripts.typecheck;
             return dependencyMap(value);
         });
         const corePath = 'node_modules/@dokebi/core/package.json';
@@ -102,19 +232,187 @@ export class ProjectInspector {
                 ...(state?.plugins.map((plugin) => plugin.id) ?? []),
                 ...result.requiredPlugins.map((plugin) => plugin.id),
             ]);
-            result.diagnostics.push(...loggingDiagnostics(config.options, known));
+            const loggerHost = state?.plugins.find((plugin) => plugin.hosts?.includes('logger'))?.id;
+            // M50: the paths name the file the app reads (configFile), as every other diagnostic.
+            // Typed with the `file` parameter of the config area's change, so this call compiles on
+            // either side of that merge (before it, the fourth argument is not read).
+            const logging = loggingDiagnostics;
+            result.diagnostics.push(...logging(config.options, known, loggerHost, configFile));
+            // D-0115: the first admin of an older recipe sits under options.blog-admin. It keeps
+            // working (the CLI reads both names); the CLI never renames a user's section itself.
+            if (Object.hasOwn(config.options, LEGACY_ADMIN_SECTION) && !known.has(LEGACY_ADMIN_SECTION)) {
+                debug('Older first-admin section in dokebi.yaml', { section: LEGACY_ADMIN_SECTION });
+                result.diagnostics.push({
+                    code: 'LEGACY_ADMIN_SECTION',
+                    severity: 'warning',
+                    path: configFile,
+                    plugin: null,
+                    details: { section: LEGACY_ADMIN_SECTION, renameTo: ADMIN_SECTION },
+                    hint: `options.${LEGACY_ADMIN_SECTION} (the first admin an older recipe wrote) keeps working and needs nothing now. Recipes now call it options.${ADMIN_SECTION}, a name not tied to one kind of app; to follow, rename the section in dokebi.yaml and the options['${LEGACY_ADMIN_SECTION}'] read in ${SEED_FILE} together (the CLI never renames them for you)`,
+                });
+            }
+        }
+        // R3 Codex T2: the app itself as a compose.yaml service on its own port, so dev-infra up
+        // started it and start, dev and verify found the port taken.
+        // R2 Codex T2: a compose.yaml that `dokebi dev-infra up` cannot start (a variable without a
+        // default that only the project's own script set) was silent here. D-0165: the passwords of
+        // dokebi.yaml that dev-infra up passes count as set.
+        const passed = Object.keys(connectionSecrets(config?.options ?? {}));
+        const envPath = await securePath(root, ENV_FILE);
+        const provided = async () => [
+            ...passed,
+            ...((await exists(envPath)) ? envKeys(await readFile(envPath, 'utf8')) : []),
+        ];
+        if (await exists(composePath)) {
+            const unset = composeUnsetVariables(await readFile(composePath, 'utf8'), await provided());
+            debug('doctor: compose.yaml variables', { unset: unset.length, passed: passed.length });
+            if (unset.length)
+                result.diagnostics.push({
+                    code: 'COMPOSE_VARIABLES_UNSET',
+                    path: COMPOSE_FILE,
+                    plugin: null,
+                    severity: 'warning',
+                    details: { variables: unset },
+                    hint: composeVariablesHint(unset),
+                });
+        }
+        const webPort = config?.options['dokebi-web']?.port;
+        if (typeof webPort === 'number' && webPort > 0 && (await exists(composePath))) {
+            const services = composeServicesPublishing(await readFile(composePath, 'utf8'), webPort);
+            debug('doctor: compose.yaml services on the web port', { port: webPort, services });
+            if (services.length)
+                result.diagnostics.push({
+                    code: 'COMPOSE_PUBLISHES_APP_PORT',
+                    path: COMPOSE_FILE,
+                    plugin: null,
+                    severity: 'warning',
+                    details: { services, port: webPort },
+                    hint: composeAppPortHint(services, webPort),
+                });
+        }
+        // R4 Codex T4: the app as a compose.yaml service built from the project (`build: .`) whose
+        // port is a variable without a default, which the port rule above cannot read.
+        if (await exists(composePath)) {
+            const text = await readFile(composePath, 'utf8');
+            const named = new Set(typeof webPort === 'number' && webPort > 0 ? composeServicesPublishing(text, webPort) : []);
+            const services = composeServicesBuildingProject(text).filter((name) => !named.has(name));
+            debug('doctor: compose.yaml services built from the project', { services });
+            if (services.length) {
+                const unset = composeUnsetVariables(text, await provided());
+                const variables = composeVariablesOf(text, services, unset);
+                result.diagnostics.push({
+                    code: 'COMPOSE_BUILDS_APP',
+                    path: COMPOSE_FILE,
+                    plugin: null,
+                    severity: 'warning',
+                    details: { services, ...(variables.length ? { variables } : {}) },
+                    hint: composeBuildsAppHint(services, variables),
+                });
+            }
+        }
+        // D-0155: the settings sections of the application, like plugin sections: their options
+        // against the schema file, and the schema file against the declaration it was written from.
+        if (config && state)
+            for (const section of state.settings ?? []) {
+                const file = settingsFile(section);
+                const schemaFile = settingsSchemaFile(section);
+                const value = Object.hasOwn(config.options, section) ? config.options[section] : undefined;
+                const checked = await check(schemaFile, () => optionsValidator.checkSettings(root, section, value ?? {}), section);
+                if (checked && !checked.schema)
+                    result.diagnostics.push({
+                        code: 'SETTINGS_SCHEMA_MISSING',
+                        severity: 'error',
+                        path: schemaFile,
+                        plugin: section,
+                        hint: 'npx dokebi settings sync writes it from the declaration',
+                    });
+                if (checked?.errors.length)
+                    result.diagnostics.push({
+                        code: 'INVALID_PLUGIN_OPTIONS',
+                        severity: 'error',
+                        path: configFile,
+                        plugin: section,
+                        details: checked.errors,
+                        hint: optionsFix(section, checked.errors, `correct options.${section} in dokebi.yaml (${schemaFile} lists the option keys)`, section, checked.schema),
+                    });
+                const rendered = await check(file, () => renderSettingsSchema(root, section), section);
+                if (rendered !== null && checked?.schema) {
+                    const current = await readFile(join(root, schemaFile), 'utf8');
+                    if (current !== rendered)
+                        result.diagnostics.push({
+                            code: 'SETTINGS_SCHEMA_STALE',
+                            severity: 'warning',
+                            path: schemaFile,
+                            plugin: section,
+                            hint: `${file} changed since its schema was written: npx dokebi settings sync`,
+                        });
+                }
+            }
+        // D-0155: a section of dokebi.yaml that nothing declares (code that reads options.<name> by
+        // hand): never checked at start, unknown to config show/set/unset/secret and the example.
+        if (config && state) {
+            const declared = new Set([
+                'logging',
+                'reload',
+                ...CONVENTION_SECTIONS,
+                // The first admin a recipe wrote, under any section name (D-0115).
+                ...adminSections(config.options),
+                ...state.plugins.flatMap((plugin) => [plugin.id, optionsKey(plugin)]),
+                ...result.requiredPlugins.map((plugin) => plugin.id),
+                ...(state.settings ?? []),
+            ]);
+            const undeclared = Object.keys(config.options).filter((section) => !declared.has(section));
+            if (undeclared.length) {
+                const packageOf = await catalogPackageOf();
+                for (const section of undeclared) {
+                    const found = undeclaredSection(section, packageOf, state.plugins.map((plugin) => plugin.id), state.settings ?? []);
+                    debug('Undeclared section in dokebi.yaml', { section, code: found.code });
+                    result.diagnostics.push({
+                        code: found.code,
+                        severity: 'warning',
+                        path: configFile,
+                        plugin: section,
+                        details: found.details,
+                        hint: `${found.message}; ${found.details.fix}`,
+                    });
+                }
+            }
         }
         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');
+            // R1 measurement: a code formatter over src/ is the usual cause; the hint says both.
+            result.diagnostics.push({
+                code: 'MODIFIED_REGISTRATION',
+                path: 'src/dokebi.generated.ts',
+                plugin: null,
+                severity: 'error',
+                hint: 'a hand edit or a code formatter (prettier, biome) changed it: restore it (git checkout -- src/dokebi.generated.ts) and keep formatters out of it (the file in .prettierignore, "!src/dokebi.generated.ts" in biome files.includes; npx dokebi check warns formatter-generated)',
+            });
         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);
-        }
+        // AI-M04 F6: a lock whose command still runs is that command's work in progress (its open
+        // transaction folder included), not an interrupted change that needs recovery.
+        const transactions = (control ?? [])
+            .filter((name) => name.startsWith('transaction-'))
+            .map((name) => `.dokebi/${name}`);
+        await check('.dokebi', async () => {
+            const holder = control?.includes('lock') ? await lockHolder(root) : null;
+            if (holder)
+                result.diagnostics.push(lockDiagnostic(holder, transactions));
+            if (holder?.running !== true)
+                // A command that ended since the listing removed its folder with the lock.
+                for (const path of transactions)
+                    if (await exists(await securePath(root, path)))
+                        result.diagnostics.push({
+                            code: 'RECOVERY_REQUIRED',
+                            severity: 'error',
+                            path,
+                            plugin: null,
+                            hint: 'an interrupted change left its transaction folder (backups of the originals). Never delete it or the lock; ask the user to look',
+                        });
+            return true;
+        });
         if (state) {
+            const ownRules = [];
             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);
@@ -131,20 +429,27 @@ export class ProjectInspector {
                     issue('MISSING_PACKAGE_DEPENDENCY', 'package.json', plugin.id);
                 if (installed)
                     matches(installed.packageName, installed.version, plugin.id);
-                const options = config && Object.hasOwn(config.options, plugin.id)
-                    ? config.options[plugin.id]
-                    : undefined;
-                const checked = installed
+                // D-0151: the logger host's options are options.logging.
+                const key = optionsKey(plugin);
+                const options = config && Object.hasOwn(config.options, key) ? config.options[key] : undefined;
+                const checked = installed && !configMissing
                     ? await check(path, async () => optionsValidator.check(root, installed, options ?? {}), plugin.id)
                     : null;
                 if (checked?.errors.length)
                     result.diagnostics.push({
                         code: 'INVALID_PLUGIN_OPTIONS',
                         severity: 'error',
-                        path: CONFIG_FILE,
+                        path: configFile,
                         plugin: plugin.id,
                         details: checked.errors,
+                        // D-0153: unknown keys name `config unset`, moved ones where they went.
+                        // The commands name the section (options.logging for the logger host, D-0151).
+                        hint: optionsFix(plugin.id, checked.errors, `correct options.${optionsKey(plugin)} in dokebi.yaml (npx dokebi plugins info ${plugin.id} --json lists the option keys)`, optionsKey(plugin), checked.schema),
                     });
+                // D-0162: the plugin's own rules once its section passes the schema (checked below, all
+                // plugins in one restricted child).
+                if (settings.runChecks && installed && config && checked && !checked.errors.length)
+                    ownRules.push(installed);
                 let documentation = null;
                 if (installed?.documentation) {
                     const candidate = 'node_modules/' + installed.packageName + '/' + installed.documentation;
@@ -178,7 +483,7 @@ export class ProjectInspector {
                             result.diagnostics.push({
                                 code: 'MISSING_REQUIRED_PLUGIN',
                                 severity: 'error',
-                                path: CONFIG_FILE,
+                                path: configFile,
                                 plugin: plugin.id,
                                 details: { requires: missing },
                             });
@@ -189,7 +494,7 @@ export class ProjectInspector {
                             result.diagnostics.push({
                                 code: 'PLUGIN_CHECK',
                                 severity: item.severity,
-                                path: CONFIG_FILE,
+                                path: configFile,
                                 plugin: plugin.id,
                                 details: {
                                     code: item.code,
@@ -210,6 +515,38 @@ export class ProjectInspector {
                         : [],
                 });
             }
+            // D-0162: the plugins' own option rules (cross-field checks the schema cannot say), as each
+            // plugin runs them when it is created at start.
+            if (ownRules.length && config) {
+                const verdicts = await check(configFile, () => checkPluginsOptions(root, ownRules, config.options));
+                for (const plugin of ownRules) {
+                    const verdict = verdicts?.get(plugin.id);
+                    if (!verdict)
+                        continue;
+                    if ('failed' in verdict) {
+                        result.diagnostics.push({
+                            code: 'PLUGIN_OPTIONS_CHECK_FAILED',
+                            severity: 'warning',
+                            path: configFile,
+                            plugin: plugin.id,
+                            details: { code: verdict.failed },
+                            hint: `the plugin's own option rules could not run here (${verdict.failed}); npx dokebi start checks them too`,
+                        });
+                        continue;
+                    }
+                    if (verdict.issues.length)
+                        result.diagnostics.push({
+                            code: 'INVALID_PLUGIN_OPTIONS',
+                            severity: 'error',
+                            path: configFile,
+                            plugin: plugin.id,
+                            details: verdict.issues,
+                            hint: `correct options.${optionsKey(plugin)} in dokebi.yaml: ${verdict.issues
+                                .map((one) => `${one.instancePath.slice(1).replaceAll('/', '.') || '(section)'} ${one.message}`)
+                                .join('; ')} (the app refuses to start with this; npx dokebi plugins info ${plugin.id} --json lists the option keys)`,
+                        });
+                }
+            }
             if (core)
                 await check('.dokebi/state.json', async () => orderPlugins(state.plugins, core, result.requiredPlugins));
             // D-0065 §11: only CLI-owned files (`owner: 'cli'`, regenerated by the CLI or a plugin) are
@@ -232,11 +569,109 @@ export class ProjectInspector {
         }
         for (const [path, expected] of originals) {
             await check(path, async () => {
-                if (hash(await readFile(await installedPath(root, path))) !== expected)
+                const text = path === configFile
+                    ? await readProjectConfigSource(root, settingsTarget.path)
+                    : await readFile(await installedPath(root, path));
+                if (hash(text) !== expected)
                     throw new CliError('CONCURRENT_CHANGE', 'Metadata changed during inspection');
                 return true;
             });
         }
+        // A file an older recipe wrote at a place the current layout moved: it keeps working.
+        for (const [path, moveTo] of Object.entries(MOVED_RECIPE_FILES)) {
+            const present = await check(path, async () => exists(await securePath(root, path)));
+            if (present)
+                result.diagnostics.push({
+                    code: 'LEGACY_LAYOUT',
+                    severity: 'warning',
+                    path,
+                    plugin: null,
+                    details: { moveTo },
+                    hint: `${path} was written by an older recipe and keeps working; the src root holds only main.ts and dokebi.generated.ts. Move it to ${moveTo}, fix its relative imports and change its import in src/main.ts to './${moveTo.slice('src/'.length)}'`,
+                });
+        }
+        // S-c: files copied from a template once are the app's, so a later fix of the template never
+        // reaches them. The fixes the installed template carries and the copy lacks are named
+        // (template-fixes.ts).
+        const installedId = (id) => result.plugins.find((item) => item.installed?.id === id)?.installed;
+        const appsHost = state?.plugins.find((plugin) => plugin.hosts?.includes('apps'));
+        const drift = await check('src/infra/db/adapters', () => templateFixes(root, root, {
+            db: installedId('dokebi-db')?.packageName,
+            apps: appsHost ? { id: appsHost.id, packageName: appsHost.packageName } : undefined,
+            inertia: installedId('dokebi-template-inertia') !== undefined,
+        }));
+        if (drift)
+            result.diagnostics.push(...drift);
+        // D-0154: an entry that does not pass configFile cannot read dokebi.yaml again; dokebi dev then
+        // restarts on every change of it (S-c). In cluster mode the workers' app is built in
+        // src/infra/runtime/application.ts (createApplication): a worker without configFile cannot
+        // take the reload its primary asks for (Studio v2, 10-31: only src/main.ts was read).
+        for (const entry of ['src/main.ts', 'src/infra/runtime/application.ts']) {
+            const text = await check(entry, async () => (await exists(await securePath(root, entry)))
+                ? await readFile(await securePath(root, entry), 'utf8')
+                : undefined);
+            // The code without comments (R13): a word in a comment wires nothing.
+            const code = typeof text === 'string'
+                ? text.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:'"`])\/\/.*$/gm, '$1')
+                : undefined;
+            if (code !== undefined &&
+                /\bnew\s+(?:Application|ClusterRunner)\s*(?:<[^>]*>)?\s*\(/.test(code) &&
+                !/\bconfigFile\s*[:,}]/.test(code))
+                result.diagnostics.push({
+                    code: 'RELOAD_NOT_WIRED',
+                    severity: 'warning',
+                    path: entry,
+                    plugin: null,
+                    hint: entry === 'src/main.ts'
+                        ? 'src/main.ts passes no configFile to new Application (or ClusterRunner), so the app never reads dokebi.yaml again: options marked reloadable need a restart, and dokebi dev restarts on every change. Add configFile: the path of dokebi.yaml, as the generated main.ts does (D-0154)'
+                        : `${entry} builds the workers' app with new Application and no configFile, so a worker cannot take the reload its primary asks for (the reload fails): pass configFile: the path of dokebi.yaml (process.env.DOKEBI_CONFIG || new URL('../../../dokebi.yaml', import.meta.url)), as @dokebi/cluster AI.md shows (D-0154)`,
+                });
+        }
+        // AI-M23: an Inertia app made before `app add --inertia` prepared the Vue type check.
+        if (pkg) {
+            const inertiaApps = await check('src/apps', () => inertiaAppNames(root));
+            // D-0129: a template-inertia without the dev file policy (no dist/vite-files.js) lets the
+            // Vite dev server of `dokebi dev` serve the whole project root, dokebi.yaml included; with
+            // devHosts (a tunnel) that is public, so it is an error then.
+            // Only an installed package is judged (a missing one is reported above).
+            const inertia = result.plugins.find((item) => item.installed?.id === 'dokebi-template-inertia')?.installed;
+            if (inertiaApps?.length && inertia) {
+                const policy = `node_modules/${inertia.packageName}/dist/vite-files.js`;
+                const guarded = await check(policy, async () => exists(await installedPath(root, policy)));
+                if (guarded === false) {
+                    const section = config?.options['dokebi-template-inertia'];
+                    const devHosts = section && typeof section === 'object' && !Array.isArray(section)
+                        ? section.devHosts
+                        : undefined;
+                    const tunnel = Array.isArray(devHosts) && devHosts.length > 0;
+                    debug('Inertia dev server without the file policy', { apps: inertiaApps, tunnel });
+                    result.diagnostics.push({
+                        code: 'DEV_FILES_UNGUARDED',
+                        severity: tunnel ? 'error' : 'warning',
+                        path: `node_modules/${inertia.packageName}`,
+                        plugin: inertia.id,
+                        details: { apps: inertiaApps, devHosts: tunnel ? devHosts.length : 0 },
+                        hint: `the installed ${inertia.packageName} has no dev file policy (D-0129): its Vite dev server answers every file of the project root (GET /build/dokebi.yaml?raw returns the configuration with its secrets, /build/src/main.ts?raw the server code)${tunnel ? ', and devHosts makes that public through the tunnel' : ''}. Upgrade it (npx dokebi upgrade ${inertia.id}); until then do not run dokebi dev behind devHosts, and change any secret that was reachable that way`,
+                    });
+                }
+            }
+            if (inertiaApps?.length &&
+                !(typeof typecheckScript === 'string' &&
+                    /\b(?:vue-tsc|typecheck-vue\.mjs)\b/.test(typecheckScript))) {
+                // The first apps host (more than one is HOST_CONFLICT elsewhere): its scaffold folder.
+                const host = state?.plugins.find((plugin) => plugin.hosts?.includes('apps'));
+                const templates = `node_modules/${host?.packageName ?? '@dokebi/app'}/templates/inertia-build`;
+                debug('Inertia apps without a Vue type check', { apps: inertiaApps });
+                result.diagnostics.push({
+                    code: 'VUE_TYPECHECK_MISSING',
+                    severity: 'warning',
+                    path: 'package.json',
+                    plugin: null,
+                    details: { apps: inertiaApps, templates },
+                    hint: `npm run typecheck checks no .vue file. Add the Vue check that dokebi app add --inertia now prepares: the devDependencies vue-tsc and @typescript/typescript6 at the versions of ${templates}/build.json, ${templates}/tsconfig.vue.json and typecheck-vue.mjs copied to the project root, ${templates}/page.d.ts copied to src/infra/inertia/page.d.ts, and " && node typecheck-vue.mjs -p tsconfig.vue.json" after the tsc of the typecheck script. They are part of the framework scaffold and need no separate permission`,
+                });
+            }
+        }
         // D-0065: AGENTS.md carries the CLI-maintained installed list between two markers.
         await check(AGENTS_FILE, async () => {
             const path = await securePath(root, AGENTS_FILE);
@@ -259,12 +694,25 @@ export class ProjectInspector {
                     plugin: null,
                     hint: `move notes outside ${INSTALLED_START} … ${INSTALLED_END} and restore the rows (one per installed package: npx dokebi inspect --json); add, upgrade and remove rewrite them`,
                 });
+            // D-0077 G: what is inside the project block is never judged, only that its markers can
+            // be found (one start, then one end, outside the installed list).
+            if (text !== null && projectBlockState(text) === 'invalid')
+                result.diagnostics.push({
+                    code: 'GUIDE_PROJECT_BLOCK_INVALID',
+                    severity: 'warning',
+                    path: AGENTS_FILE,
+                    plugin: null,
+                    hint: `keep exactly one ${PROJECT_START} line and, after it, one ${PROJECT_END} line in AGENTS.md, outside the dokebi:installed block (remove the extra or misplaced marker, keep your text); until then add, upgrade and remove leave AGENTS.md alone`,
+                });
             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');
+                !result.diagnostics.some((item) => item.code === 'PROJECT_LOCKED')) {
+                const late = await lockHolder(root);
+                if (late)
+                    result.diagnostics.push(lockDiagnostic(late, []));
+            }
             return true;
         });
         result.healthy = !result.diagnostics.some((item) => item.severity === 'error');

package/dist/project-state.d.ts

@@ -30,6 +30,11 @@ export interface ProjectState {
     apps?: string[];
     /** Modules in registration order (src/shared/modules/<name>), D-0032, for the modules host. */
     modules?: string[];
+    /**
+     * D-0155: the settings sections of the application (options.<section>), declared in
+     * src/shared/settings/<section>.ts with their schema beside it.
+     */
+    settings?: string[];
 }
 /** App and template names: lower-case letters, digits and hyphens, starting with a letter. */
 export declare const APP_NAME: RegExp;