@dokebi/cli 0.2.5 → 0.4.0

package/dist/configuration.js

@@ -39,7 +39,8 @@ export function renderConfig(document) {
     }
     return document.toString();
 }
-export const CONFIG_IGNORES = ['dokebi.yaml', 'dokebi.json', '.dokebi/dokebi.json.backup'];
+/** Never committed: real settings, the legacy backup and the generated secrets in .env (D-0073). */
+export const CONFIG_IGNORES = ['dokebi.yaml', 'dokebi.json', '.dokebi/dokebi.json.backup', '.env'];
 export function parseProjectConfig(source) {
     try {
         return readConfig(parseConfig(source));

package/dist/dev-infra.d.ts

@@ -0,0 +1,62 @@
+import type { CatalogVariant } from './catalog.js';
+export declare const COMPOSE_FILE = "compose.yaml";
+export { ENV_FILE } from './env-file.js';
+export declare const PASSWORD_VARIABLE = "DOKEBI_DB_PASSWORD";
+export declare const DB_SERVICE = "db";
+/** A connection URL that still has to be written (url mode) starts with this. */
+export declare const URL_PLACEHOLDER_PREFIX = "<";
+export type DockerSettings = NonNullable<NonNullable<CatalogVariant['devInfra']>['docker']>;
+/** URL-safe random password (no characters that need escaping in a URL or compose file). */
+export declare function generatePassword(): string;
+/** The value of one variable in a .env text (KEY=value lines), or undefined. */
+export declare function envValue(text: string, name: string): string | undefined;
+/** Appends `name=value` to a .env text. */
+export declare function withEnv(text: string, name: string, value: string, comment: string): string;
+/**
+ * The npm and Compose project name when the folder name leaves nothing usable. It names the
+ * user's project, not a plugin (it predates D-0070 and is kept so existing projects keep theirs).
+ */
+export declare const FALLBACK_PROJECT_NAME = "dokebi-app";
+/** Compose project names: lower-case letters, digits, dashes and underscores. */
+export declare function composeProject(name: string): string;
+/** The compose.yaml text of the development database (the developer owns it afterwards). */
+export declare function composeText(project: string, variant: string, docker: DockerSettings, port: number): string;
+/** The connection URL from the variant template. */
+export declare function connectionUrl(docker: DockerSettings, password: string, port: number): string;
+/** The same URL with the password hidden, for results and logs. */
+export declare function redactUrl(url: string): string;
+/**
+ * Whether a TCP port on 127.0.0.1 is taken: something accepts connections, or this process
+ * cannot listen there (BSD lets a specific address bind next to a wildcard listener, so both).
+ */
+export declare function portInUse(port: number): Promise<boolean>;
+/** The first free port after `port` (up to 100 tries), to name in PORT_IN_USE; never used silently. */
+export declare function freePortAfter(port: number): Promise<number | undefined>;
+/**
+ * A taken port is the user's call (AI-M03): the question to ask and what to do now. `delegated`:
+ * the user left the choices to the agent (--defaults / --answers-from defaults), so the agent may
+ * take the proposed port and must tell the user; otherwise it asks and ends its turn.
+ */
+export declare function portQuestion(input: {
+    readonly what: 'Web' | 'Database';
+    readonly port: number;
+    readonly alternative: number | undefined;
+    readonly flag: '--port' | '--db-port';
+    readonly delegated: boolean;
+}): {
+    waitForUser: boolean;
+    question: string;
+    next: string;
+};
+/**
+ * Whether an executable named `name` is in a PATH folder: a cheap check (no process, no daemon
+ * call) for the questions (AI-M03). It does not prove that the program runs.
+ */
+export declare function commandOnPath(name: string, path?: string): boolean;
+/** `docker version` and `docker compose version` both answer: Docker can run the database. */
+export declare function dockerAvailable(): Promise<{
+    ok: boolean;
+    error?: string;
+}>;
+/** Whether the compose service of this project runs (a later recipe run skips `up`). */
+export declare function composeServiceRunning(root: string): Promise<boolean>;

package/dist/dev-infra.js

@@ -0,0 +1,215 @@
+// Development infrastructure (D-0065): compose.yaml for the database a project uses, the
+// generated password in .env and the matching dokebi.yaml address. Docker data comes from the
+// db package's `dokebiCatalog.variants[].devInfra.docker`.
+import { execFile } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { statSync } from 'node:fs';
+import { connect, createServer } from 'node:net';
+import { delimiter, join } from 'node:path';
+import { promisify } from 'node:util';
+import { stringify } from 'yaml';
+import { debug, describeError, isMissing } from './diagnostics.js';
+const exec = promisify(execFile);
+export const COMPOSE_FILE = 'compose.yaml';
+export { ENV_FILE } from './env-file.js';
+export const PASSWORD_VARIABLE = 'DOKEBI_DB_PASSWORD';
+export const DB_SERVICE = 'db';
+/** A connection URL that still has to be written (url mode) starts with this. */
+export const URL_PLACEHOLDER_PREFIX = '<';
+/** URL-safe random password (no characters that need escaping in a URL or compose file). */
+export function generatePassword() {
+    return randomBytes(18).toString('base64url');
+}
+/** The value of one variable in a .env text (KEY=value lines), or undefined. */
+export function envValue(text, name) {
+    for (const line of text.split(/\r?\n/)) {
+        const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+        if (match?.[1] === name)
+            return (match[2] ?? '').trim().replace(/^(['"])(.*)\1$/, '$2');
+    }
+    return undefined;
+}
+/** Appends `name=value` to a .env text. */
+export function withEnv(text, name, value, comment) {
+    return `${text}${text && !text.endsWith('\n') ? '\n' : ''}# ${comment}\n${name}=${value}\n`;
+}
+/**
+ * The npm and Compose project name when the folder name leaves nothing usable. It names the
+ * user's project, not a plugin (it predates D-0070 and is kept so existing projects keep theirs).
+ */
+export const FALLBACK_PROJECT_NAME = 'dokebi-app';
+/** Compose project names: lower-case letters, digits, dashes and underscores. */
+export function composeProject(name) {
+    const cleaned = name
+        .toLowerCase()
+        .replace(/^@[^/]+\//, '')
+        .replace(/[^a-z0-9_-]+/g, '-')
+        .replace(/^[^a-z0-9]+/, '');
+    return cleaned || FALLBACK_PROJECT_NAME;
+}
+/** Where the image keeps its data (a named volume is mounted there). */
+function dataDirectory(image) {
+    if (image.startsWith('postgres'))
+        return '/var/lib/postgresql/data';
+    if (image.startsWith('mongo'))
+        return '/data/db';
+    return '/var/lib/mysql';
+}
+/** The compose.yaml text of the development database (the developer owns it afterwards). */
+export function composeText(project, variant, docker, port) {
+    const interpolate = (value) => value.replaceAll(`\${${PASSWORD_VARIABLE}}`, `\${${PASSWORD_VARIABLE}:?set ${PASSWORD_VARIABLE} in .env (npx dokebi dev-infra writes it)}`);
+    const document = {
+        name: project,
+        services: {
+            [DB_SERVICE]: {
+                image: docker.image,
+                restart: 'unless-stopped',
+                environment: Object.fromEntries(Object.entries(docker.env).map(([key, value]) => [key, interpolate(value)])),
+                ports: [`127.0.0.1:${port}:${docker.port}`],
+                volumes: [`db-data:${dataDirectory(docker.image)}`],
+                healthcheck: {
+                    test: docker.healthcheck.map(interpolate),
+                    interval: '2s',
+                    timeout: '5s',
+                    retries: 60,
+                },
+            },
+        },
+        volumes: { 'db-data': {} },
+    };
+    return `# Development ${variant} database of this project, written by \`npx dokebi dev-infra\`.
+# It is yours to change. The password is read from .env (not committed); dokebi.yaml holds the
+# same address for the app. Start: docker compose up -d --wait · Stop: docker compose down
+# (add -v to delete the data volume).
+${stringify(document, { lineWidth: 0 })}`;
+}
+/** The connection URL from the variant template. */
+export function connectionUrl(docker, password, port) {
+    return docker.url
+        .replace('{password}', encodeURIComponent(password))
+        .replace('{port}', String(port));
+}
+/** The same URL with the password hidden, for results and logs. */
+export function redactUrl(url) {
+    return url.replace(/\/\/([^:/@]*):[^@/]*@/, '//$1:***@');
+}
+/**
+ * Whether a TCP port on 127.0.0.1 is taken: something accepts connections, or this process
+ * cannot listen there (BSD lets a specific address bind next to a wildcard listener, so both).
+ */
+export async function portInUse(port) {
+    const accepts = await new Promise((resolve) => {
+        const socket = connect({ host: '127.0.0.1', port });
+        socket.setTimeout(1000);
+        socket.once('connect', () => {
+            socket.destroy();
+            resolve(true);
+        });
+        socket.once('timeout', () => {
+            socket.destroy();
+            resolve(false);
+        });
+        // Refused or unreachable is the answer "nothing accepts there", not a failure.
+        socket.once('error', (error) => {
+            debug('Port probe connect failed', { port, code: error.code });
+            resolve(false);
+        });
+    });
+    if (accepts)
+        return true;
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once('error', (error) => {
+            debug('Port probe could not listen', { port, code: error.code });
+            resolve(true);
+        });
+        server.listen(port, '127.0.0.1', () => server.close(() => resolve(false)));
+    });
+}
+/** The first free port after `port` (up to 100 tries), to name in PORT_IN_USE; never used silently. */
+export async function freePortAfter(port) {
+    for (let candidate = port + 1; candidate <= Math.min(65535, port + 100); candidate++)
+        if (!(await portInUse(candidate)))
+            return candidate;
+    return undefined;
+}
+/**
+ * A taken port is the user's call (AI-M03): the question to ask and what to do now. `delegated`:
+ * the user left the choices to the agent (--defaults / --answers-from defaults), so the agent may
+ * take the proposed port and must tell the user; otherwise it asks and ends its turn.
+ */
+export function portQuestion(input) {
+    const { what, port, alternative, flag, delegated } = input;
+    const proposal = alternative ?? '<free port>';
+    const question = `${what} port ${port} is in use by another program. Use port ${proposal} instead (${flag} ${proposal}), or stop the program that uses ${port} and keep ${port}?`;
+    const rule = 'do not pick the port yourself unless the user left choices to you (--defaults / --answers-from defaults)';
+    return {
+        waitForUser: !delegated,
+        question,
+        next: delegated
+            ? `The user left the choices to you (--defaults), so you may run the same command again with ${flag} ${proposal}; tell the user the port you chose and why (${port} was in use). Nothing was changed. Otherwise ${rule}.`
+            : `Ask the user this question and end your turn; ${rule}. Nothing was changed. After the answer, run the same command again with ${flag} <the chosen port>, or as it was once the user stopped the other program.`,
+    };
+}
+/**
+ * Whether an executable named `name` is in a PATH folder: a cheap check (no process, no daemon
+ * call) for the questions (AI-M03). It does not prove that the program runs.
+ */
+export function commandOnPath(name, path = process.env.PATH ?? '') {
+    const names = process.platform === 'win32'
+        ? (process.env.PATHEXT ?? '.EXE;.CMD;.BAT').split(';').map((ext) => `${name}${ext}`)
+        : [name];
+    for (const folder of path.split(delimiter)) {
+        if (!folder)
+            continue;
+        for (const file of names) {
+            let found = false;
+            try {
+                found = statSync(join(folder, file)).isFile();
+            }
+            catch (error) {
+                // Not there (ENOENT, or ENOTDIR for a PATH entry that is a file) is the usual answer; a
+                // folder this user may not read (EACCES) cannot hold a command they can run either.
+                if (!isMissing(error))
+                    debug('A PATH folder could not be read while looking for a command', {
+                        name,
+                        folder,
+                        error: describeError(error),
+                    });
+            }
+            if (found) {
+                debug('Command found on PATH', { name, file: join(folder, file) });
+                return true;
+            }
+        }
+    }
+    debug('Command not found on PATH', { name });
+    return false;
+}
+/** `docker version` and `docker compose version` both answer: Docker can run the database. */
+export async function dockerAvailable() {
+    try {
+        await exec('docker', ['version', '--format', '{{.Server.Version}}'], { timeout: 15_000 });
+        await exec('docker', ['compose', 'version'], { timeout: 15_000 });
+        return { ok: true };
+    }
+    catch (error) {
+        debug('Docker is not available', { error: describeError(error) });
+        return {
+            ok: false,
+            error: error.stderr?.trim() || error.message,
+        };
+    }
+}
+/** Whether the compose service of this project runs (a later recipe run skips `up`). */
+export async function composeServiceRunning(root) {
+    try {
+        const { stdout } = await exec('docker', ['compose', 'ps', '--status', 'running', '--services'], { cwd: root, timeout: 15_000 });
+        return stdout.split('\n').includes(DB_SERVICE);
+    }
+    catch (error) {
+        // "Not running" makes the recipe run `docker compose up`, which reports the real failure.
+        debug('docker compose ps failed', { error: describeError(error) });
+        return false;
+    }
+}

package/dist/env-file.d.ts

@@ -0,0 +1,24 @@
+/** The file `dokebi dev-infra` and plugin installs write and the server commands read. */
+export declare const ENV_FILE = ".env";
+/**
+ * Checks that every line of a .env text is blank, a comment or `KEY=value` (a quoted value may
+ * span lines and must be closed). The values themselves are left to `util.parseEnv`; the error
+ * names the line only, never its content.
+ */
+export declare function checkEnvText(text: string): void;
+/**
+ * The variables of `<root>/.env` (empty when there is none). Throws ENV_FILE_INVALID when the
+ * file cannot be read or a line is not `KEY=value`.
+ */
+export declare function readEnvFile(root: string): Record<string, string>;
+/**
+ * The environment of an app the CLI runs: the project's .env, then the CLI's own environment on
+ * top (it wins), then NODE_ENV (`mode` unless one of them set it) and `extra` (the CLI's own
+ * variables such as DOKEBI_DEV or the verify and instance tokens).
+ */
+export declare function appEnvironment(root: string, mode: string, extra?: Readonly<Record<string, string>>, fileValues?: Readonly<Record<string, string>>): NodeJS.ProcessEnv;
+/** Whether a variable is set in the environment or in the project's .env (values not returned). */
+export declare function envHas(root: string, name: string): {
+    environment: boolean;
+    file: boolean;
+};

package/dist/env-file.js

@@ -0,0 +1,100 @@
+// The project's `.env` for the apps the CLI runs (D-0073): `dokebi dev`, `start` (and
+// `start --foreground`) and `verify` pass its variables to the app. Variables already set in the
+// environment win, so a shell, a CI job or a production secret manager always decides. Values
+// are never printed or logged; only the file and the variable names are (debug). A file that
+// cannot be read or has a line that is not `KEY=value` is a coded error (ENV_FILE_INVALID), not
+// silently skipped: an app that starts without the secret it expects is harder to explain.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseEnv } from 'node:util';
+import { debug, isMissing } from './diagnostics.js';
+import { CliError } from './errors.js';
+/** The file `dokebi dev-infra` and plugin installs write and the server commands read. */
+export const ENV_FILE = '.env';
+const ASSIGNMENT = /^\s*(?:export\s+)?[A-Za-z_][A-Za-z0-9_.-]*\s*=(.*)$/;
+function invalid(line, reason) {
+    return new CliError('ENV_FILE_INVALID', `${ENV_FILE} line ${line}: ${reason}`, {
+        details: {
+            file: ENV_FILE,
+            line,
+            fix: `edit ${ENV_FILE}: one KEY=value per line (# starts a comment; quote values with spaces or several lines), or remove the line`,
+        },
+    });
+}
+/**
+ * Checks that every line of a .env text is blank, a comment or `KEY=value` (a quoted value may
+ * span lines and must be closed). The values themselves are left to `util.parseEnv`; the error
+ * names the line only, never its content.
+ */
+export function checkEnvText(text) {
+    const lines = text.split(/\r?\n/);
+    for (let index = 0; index < lines.length; index++) {
+        const line = lines[index] ?? '';
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const match = ASSIGNMENT.exec(line);
+        if (!match)
+            throw invalid(index + 1, 'not a KEY=value line');
+        const value = (match[1] ?? '').trimStart();
+        const quote = value[0];
+        if (quote !== '"' && quote !== "'" && quote !== '`')
+            continue;
+        if (value.indexOf(quote, 1) !== -1)
+            continue;
+        // A quoted value that goes on: it ends on the first later line with the same quote.
+        const opened = index + 1;
+        do {
+            index++;
+            if (index >= lines.length)
+                throw invalid(opened, `the ${quote} quote is never closed`);
+        } while (!(lines[index] ?? '').includes(quote));
+    }
+}
+/**
+ * The variables of `<root>/.env` (empty when there is none). Throws ENV_FILE_INVALID when the
+ * file cannot be read or a line is not `KEY=value`.
+ */
+export function readEnvFile(root) {
+    const file = join(root, ENV_FILE);
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch (error) {
+        if (isMissing(error))
+            return {};
+        throw new CliError('ENV_FILE_INVALID', `Unable to read ${ENV_FILE}`, {
+            cause: error,
+            details: {
+                file: ENV_FILE,
+                fix: `make ${ENV_FILE} a readable file (or remove it)`,
+            },
+        });
+    }
+    checkEnvText(text);
+    const values = parseEnv(text);
+    debug('Read the project .env for the app', { file, variables: Object.keys(values) });
+    return values;
+}
+/**
+ * The environment of an app the CLI runs: the project's .env, then the CLI's own environment on
+ * top (it wins), then NODE_ENV (`mode` unless one of them set it) and `extra` (the CLI's own
+ * variables such as DOKEBI_DEV or the verify and instance tokens).
+ */
+export function appEnvironment(root, mode, extra = {}, fileValues = readEnvFile(root)) {
+    const overridden = Object.keys(fileValues).filter((key) => process.env[key] !== undefined);
+    if (overridden.length)
+        debug('Variables of .env already set in the environment; the environment wins', {
+            variables: overridden,
+        });
+    const merged = { ...fileValues, ...process.env };
+    return { ...merged, NODE_ENV: merged.NODE_ENV ?? mode, ...extra };
+}
+/** Whether a variable is set in the environment or in the project's .env (values not returned). */
+export function envHas(root, name) {
+    return {
+        environment: process.env[name] !== undefined,
+        file: Object.hasOwn(readEnvFile(root), name),
+    };
+}

package/dist/generator.d.ts

@@ -1,5 +1,19 @@
-import type { PluginManifest } from './manifest.js';
+import { type PluginManifest } from './manifest.js';
 import type { Installation } from './project-state.js';
+/**
+ * src/dokebi.generated.ts: imports every installed plugin and registers it in dependency order.
+ *
+ * Options are not checked here. Each plugin's factory parses its `options.<id>` section with its
+ * own declaration (D-0063 §3, `defineOptions`) when `registerPlugins` calls it, so an invalid
+ * dokebi.yaml still fails at startup — with `INVALID_PLUGIN_OPTIONS`, the plugin id, the option
+ * paths and a fix — without loading a JSON Schema validator (D-0070 §4: compiling the schemas
+ * with Ajv was about 40% of an 11-plugin start). `dokebi doctor`, `add` and `config set` still
+ * check the options.schema.json files offline.
+ *
+ * The CLI-managed units reach the plugin whose manifest declares their role (D-0070
+ * `dokebi.hosts`): `apps` (`dokebi app add`, src/apps/<name>/app.ts) and `modules`
+ * (`dokebi module add`, src/shared/modules/<name>/module.ts).
+ */
 export declare function generateRegistration(plugins: PluginManifest[], installations?: Readonly<Record<string, Installation>>, apps?: readonly string[], modules?: readonly string[]): string;
 export declare const LEGACY_MAIN_SOURCE = "import { Application } from '@dokebi/core';\nimport { registerPlugins } from './dokebi.generated.ts';\n\nconst app = new Application();\nregisterPlugins(app);\nawait app.start();\ntry {\n  app.logger.log('info', 'Dokebi application started');\n  // Run local work here. Long-running apps own their signal and shutdown policy.\n} finally {\n  await app.stop();\n}\n";
 /** The 0.2.0 YAML entry point before it became long-running; migrate still recognizes it. */
@@ -10,4 +24,13 @@ export declare const MAIN_SOURCE = "import { Application, loadConfig } from '@do
  * editor and `tsc` should reject syntax Node cannot run (erasableSyntaxOnly) and need explicit
  * `.ts` imports and `import type` (allowImportingTsExtensions, verbatimModuleSyntax).
  */
+/**
+ * Development tools `dokebi init` pins in a new project (stage 3 §0). `@dokebi/cli` is the CLI
+ * that created the project, so `npx dokebi` inside it runs the local bin and never npm's
+ * unrelated `dokebi` package. TypeScript and the Node types back `npm run typecheck`; their
+ * versions follow this repository's pins (a CLI test compares them with the root package.json).
+ */
+export declare const PROJECT_DEV_DEPENDENCIES: Readonly<Record<string, string>>;
+/** `npm run typecheck`: the checks of the generated tsconfig.json (it already sets noEmit). */
+export declare const TYPECHECK_SCRIPT = "tsc -p tsconfig.json --noEmit";
 export declare const TSCONFIG_SOURCE: string;

package/dist/generator.js

@@ -1,31 +1,59 @@
+import { hostOf } from './manifest.js';
+import { CLI_VERSION } from './output.js';
 /** Import specifier of a user entry file, relative to src/dokebi.generated.ts. */
 function entrySpecifier(target) {
     return './' + target.slice('src/'.length);
 }
+/**
+ * src/dokebi.generated.ts: imports every installed plugin and registers it in dependency order.
+ *
+ * Options are not checked here. Each plugin's factory parses its `options.<id>` section with its
+ * own declaration (D-0063 §3, `defineOptions`) when `registerPlugins` calls it, so an invalid
+ * dokebi.yaml still fails at startup — with `INVALID_PLUGIN_OPTIONS`, the plugin id, the option
+ * paths and a fix — without loading a JSON Schema validator (D-0070 §4: compiling the schemas
+ * with Ajv was about 40% of an 11-plugin start). `dokebi doctor`, `add` and `config set` still
+ * check the options.schema.json files offline.
+ *
+ * The CLI-managed units reach the plugin whose manifest declares their role (D-0070
+ * `dokebi.hosts`): `apps` (`dokebi app add`, src/apps/<name>/app.ts) and `modules`
+ * (`dokebi module add`, src/shared/modules/<name>/module.ts).
+ */
 export function generateRegistration(plugins, installations = {}, apps = [], modules = []) {
+    for (const [role, units] of [
+        ['apps', apps],
+        ['modules', modules],
+    ])
+        if (units.length)
+            hostOf(plugins, role);
     const imports = [];
     const factories = [];
+    /** Plugins the CLI passes an entry (an entry file or the units they host). */
+    const withEntry = new Set();
     plugins.forEach((plugin, index) => {
         imports.push(`import { createPlugin as factory${index} } from ${JSON.stringify(plugin.packageName)};`);
         const entry = installations[plugin.id]?.entry;
-        if (entry)
+        if (entry) {
             imports.push(`import * as entry${index} from ${JSON.stringify(entrySpecifier(entry))};`);
+            withEntry.add(plugin.id);
+        }
         let entryCode = entry ? `, entry: entry${index}` : '';
-        // dokebi-app receives the apps recorded by `dokebi app add` (src/apps/<name>/app.ts).
-        if (plugin.id === 'dokebi-app') {
+        // The apps host receives the apps recorded by `dokebi app add` (src/apps/<name>/app.ts).
+        if (plugin.hosts?.includes('apps')) {
             apps.forEach((name, appIndex) => {
                 imports.push(`import app${appIndex} from ${JSON.stringify(`./apps/${name}/app.ts`)};`);
             });
             entryCode = `, entry: { apps: { ${apps.map((name, appIndex) => `${JSON.stringify(name)}: app${appIndex}`).join(', ')} } }`;
+            withEntry.add(plugin.id);
         }
-        // dokebi-module receives the modules recorded by `dokebi module add` (D-0032), after the
+        // The modules host receives the modules recorded by `dokebi module add` (D-0032), after the
         // list of an older entry file (src/shared/modules/index.ts) when the project still has one.
-        if (plugin.id === 'dokebi-module' && modules.length) {
+        if (plugin.hosts?.includes('modules') && modules.length) {
             modules.forEach((name, moduleIndex) => {
                 imports.push(`import module${moduleIndex} from ${JSON.stringify(`./shared/modules/${name}/module.ts`)};`);
             });
             const list = modules.map((_name, moduleIndex) => `module${moduleIndex}`);
             entryCode = `, entry: { modules: [${[...(entry ? [`...entry${index}.modules`] : []), ...list].join(', ')}] }`;
+            withEntry.add(plugin.id);
         }
         factories.push(`    factory${index}({ app: app.view, options: optionsOf(${JSON.stringify(plugin.id)})${entryCode} }),`);
     });
@@ -35,22 +63,10 @@ export function generateRegistration(plugins, installations = {}, apps = [], mod
         id: plugin.id,
         version: plugin.version,
         dependencies: plugin.dependencies.map((dependency) => dependency.name),
-        entry: Boolean(installations[plugin.id]?.entry) ||
-            plugin.id === 'dokebi-app' ||
-            (plugin.id === 'dokebi-module' && modules.length > 0),
-    }));
-    // Schemas are found through module resolution, so hoisted installs (npm workspaces,
-    // monorepos) work the same as a project-local node_modules.
-    const schemas = plugins
-        .filter((plugin) => plugin.optionsSchema)
-        .map((plugin) => ({
-        id: plugin.id,
-        packageName: plugin.packageName,
-        file: plugin.optionsSchema,
+        entry: withEntry.has(plugin.id),
     }));
     return `// Generated by dokebi. Change dokebi.yaml options or plugin entry files instead of this file.
-import { readFile } from 'node:fs/promises';
-import { type Application, ConfigValidator, loadSchema, type Plugin } from '@dokebi/core';
+import type { Application, Plugin } from '@dokebi/core';
 ${imports.join('\n')}
 
 const MANIFESTS: readonly {
@@ -59,39 +75,16 @@ const MANIFESTS: readonly {
   dependencies: readonly string[];
   entry: boolean;
 }[] = ${JSON.stringify(manifests)};
-const SCHEMAS: readonly { id: string; packageName: string; file: string }[] = ${JSON.stringify(schemas)};
-
-/** A file inside an installed package, found from the package entry the app resolves. */
-async function packageFile(packageName: string, file: string): Promise<URL> {
-  let directory = new URL('.', import.meta.resolve(packageName));
-  for (;;) {
-    try {
-      const manifest: unknown = JSON.parse(await readFile(new URL('package.json', directory), 'utf8'));
-      if (manifest !== null && typeof manifest === 'object' && 'name' in manifest && manifest.name === packageName)
-        return new URL(file, directory);
-    } catch (cause) {
-      if ((cause as { code?: unknown }).code !== 'ENOENT') throw cause;
-    }
-    const parent = new URL('..', directory);
-    if (parent.href === directory.href) throw new Error('Installed package not found: ' + packageName);
-    directory = parent;
-  }
-}
 
+/**
+ * Creates and registers the installed plugins. Each factory checks its options.<plugin> section
+ * of dokebi.yaml with the plugin's own declaration; an invalid value fails here with
+ * INVALID_PLUGIN_OPTIONS (the plugin, the option paths and a fix).
+ */
 export async function registerPlugins(app: Application): Promise<void> {
   const options: Record<string, unknown> = app.config;
   const optionsOf = (id: string): unknown =>
     Object.hasOwn(options, id) && options[id] !== null ? options[id] : {};
-  const validator = new ConfigValidator();
-  for (const schema of SCHEMAS) {
-    let loaded: Record<string, unknown>;
-    try {
-      loaded = await loadSchema(await packageFile(schema.packageName, schema.file));
-    } catch (cause) {
-      throw new Error('Unable to load the options schema of plugin ' + schema.id, { cause });
-    }
-    await validator.validate(loaded, optionsOf(schema.id));
-  }
   const plugins: Plugin<unknown>[] = [
 ${factories.join('\n')}
   ];
@@ -152,6 +145,19 @@ process.once('beforeExit', () => void stop('idle'));
  * editor and `tsc` should reject syntax Node cannot run (erasableSyntaxOnly) and need explicit
  * `.ts` imports and `import type` (allowImportingTsExtensions, verbatimModuleSyntax).
  */
+/**
+ * Development tools `dokebi init` pins in a new project (stage 3 §0). `@dokebi/cli` is the CLI
+ * that created the project, so `npx dokebi` inside it runs the local bin and never npm's
+ * unrelated `dokebi` package. TypeScript and the Node types back `npm run typecheck`; their
+ * versions follow this repository's pins (a CLI test compares them with the root package.json).
+ */
+export const PROJECT_DEV_DEPENDENCIES = {
+    '@dokebi/cli': CLI_VERSION,
+    '@types/node': '24.19.2',
+    typescript: '7.0.2',
+};
+/** `npm run typecheck`: the checks of the generated tsconfig.json (it already sets noEmit). */
+export const TYPECHECK_SCRIPT = 'tsc -p tsconfig.json --noEmit';
 export const TSCONFIG_SOURCE = `${JSON.stringify({
     compilerOptions: {
         target: 'ES2023',
@@ -161,8 +167,12 @@ export const TSCONFIG_SOURCE = `${JSON.stringify({
         noEmit: true,
         allowImportingTsExtensions: true,
         erasableSyntaxOnly: true,
+        // D-0064: overriding an extension hook needs `override`, so a misspelt hook is an error.
+        noImplicitOverride: true,
         verbatimModuleSyntax: true,
         skipLibCheck: true,
+        // TypeScript 6+ no longer loads every @types package; init installs @types/node.
+        types: ['node'],
     },
     include: ['src/**/*.ts'],
 }, null, 2)}\n`;

package/dist/guide.d.ts

@@ -0,0 +1,29 @@
+import type { Catalog } from './catalog.js';
+/** One step of the AI flow: a command and why. */
+export interface GuideStep {
+    readonly command: string;
+    readonly why: string;
+}
+export interface Guide {
+    readonly cliVersion: string;
+    /** The flow from a one-line request ("make me a blog") to a verified app. */
+    readonly steps: readonly GuideStep[];
+    /** Rules that hold during every step. */
+    readonly rules: readonly string[];
+    readonly recipes: readonly {
+        name: string;
+        summary: string;
+        questions: readonly string[];
+    }[];
+    readonly absent: readonly string[];
+    readonly commands: readonly {
+        usage: string;
+        summary: string;
+    }[];
+    readonly text: string;
+}
+/** The short pointer printed at the top of `dokebi --help`. */
+export declare const HELP_POINTER = "AI and automation: read `dokebi guide` (--json) first. Ask the user every choice and end your turn until they answer; finish with `dokebi verify` and say done only when it is ok. Every command takes --json and changing commands take --dry-run. Outside a project run npx -y @dokebi/cli (inside, npx dokebi uses the project copy); the npm package named \"dokebi\" is not this CLI\n";
+export declare const GUIDE_STEPS: readonly GuideStep[];
+export declare const GUIDE_RULES: readonly string[];
+export declare function buildGuide(catalog: Catalog): Guide;