@dokebi/cli 0.1.0 → 0.2.0

package/dist/configuration-scaffold.js

@@ -0,0 +1,150 @@
+import { isMap, isNode, parseDocument } from 'yaml';
+import { parseProjectConfig, renderConfig } from './configuration.js';
+const SENSITIVE = /(?:password|passwd|secret|token|credential|api.?key|private.?key|connection.?string|url|uri|host|address|endpoint|servers?)/i;
+const ADDRESS = /^(?:[a-z][a-z0-9+.-]*:\/\/|localhost(?::|$)|(?:\d{1,3}\.){3}\d{1,3}(?::|$))/i;
+const FORBIDDEN = new Set(['__proto__', '<<']);
+const COMPOSITE = [
+    '$ref',
+    '$dynamicRef',
+    'allOf',
+    'anyOf',
+    'oneOf',
+    'not',
+    'if',
+    'then',
+    'else',
+    'dependentSchemas',
+];
+const composite = (schema) => COMPOSITE.some((key) => Object.hasOwn(schema, key));
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function description(value) {
+    if (typeof value !== 'string')
+        return '';
+    let result = '';
+    let inControlRun = false;
+    for (const character of value) {
+        const code = character.charCodeAt(0);
+        if (code <= 0x1f || code === 0x7f) {
+            if (!inControlRun)
+                result += ' ';
+            inControlRun = true;
+        }
+        else {
+            result += character;
+            inControlRun = false;
+        }
+        if (result.length >= 240)
+            break;
+    }
+    return result.slice(0, 240);
+}
+function safeDefault(value, schema, path) {
+    if (composite(schema) ||
+        schema.writeOnly === true ||
+        path.some((key) => SENSITIVE.test(key) || FORBIDDEN.has(key)))
+        return false;
+    if (value === null || typeof value === 'boolean')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (typeof value === 'string')
+        return value.length <= 256 && !ADDRESS.test(value);
+    if (Array.isArray(value))
+        return (value.length <= 100 &&
+            (value.length === 0 ||
+                (record(schema.items) &&
+                    value.every((item) => safeDefault(item, schema.items, path)))));
+    if (record(value)) {
+        if (Object.keys(value).length > 100)
+            return false;
+        const properties = record(schema.properties) ? schema.properties : {};
+        return Object.entries(value).every(([key, child]) => record(properties[key]) &&
+            safeDefault(child, properties[key], [...path, key]));
+    }
+    return false;
+}
+export function scaffoldConfig(source, id, schema) {
+    parseProjectConfig(source);
+    const document = parseDocument(source, { version: '1.2' });
+    const base = ['options', id];
+    if (!document.hasIn(base))
+        document.setIn(base, document.createNode({}));
+    const lines = [
+        'Configuration for ' + id + '. Values marked required must be set before starting.',
+    ];
+    let visited = 0;
+    const visit = (current, path, names, depth, allowDefaults) => {
+        if (depth > 12 || visited >= 200)
+            return;
+        const properties = record(current.properties) ? current.properties : {};
+        const required = new Set(Array.isArray(current.required)
+            ? current.required.filter((value) => typeof value === 'string')
+            : []);
+        for (const [name, candidate] of Object.entries(properties)) {
+            if (++visited > 200) {
+                lines.push('Additional fields: see the installed options schema.');
+                break;
+            }
+            if (!record(candidate))
+                continue;
+            const keys = [...path, name];
+            const labels = [...names, name];
+            const label = labels.map((key) => JSON.stringify(key)).join('.');
+            const type = typeof candidate.type === 'string'
+                ? candidate.type
+                : Array.isArray(candidate.type)
+                    ? candidate.type.filter((item) => typeof item === 'string').join('|')
+                    : 'schema-defined';
+            const note = description(candidate.description);
+            lines.push(label +
+                ' (' +
+                type +
+                ', ' +
+                (required.has(name) ? 'required' : 'optional') +
+                ')' +
+                (note ? ': ' + note : ''));
+            const parent = document.getIn(path, true);
+            const writable = !document.hasIn(path) || isMap(parent);
+            const canDefault = allowDefaults &&
+                current.writeOnly !== true &&
+                candidate.writeOnly !== true &&
+                !composite(current) &&
+                !composite(candidate);
+            if (canDefault &&
+                writable &&
+                !document.hasIn(keys) &&
+                Object.hasOwn(candidate, 'default') &&
+                safeDefault(candidate.default, candidate, labels) &&
+                !FORBIDDEN.has(name)) {
+                for (let length = base.length + 1; length < keys.length; length++) {
+                    const parentPath = keys.slice(0, length);
+                    if (!document.hasIn(parentPath))
+                        document.setIn(parentPath, document.createNode({}));
+                }
+                document.setIn(keys, document.createNode(candidate.default));
+            }
+            if (candidate.type === 'object' && record(candidate.properties)) {
+                const present = document.hasIn(keys);
+                const child = document.getIn(keys, true);
+                const canDescend = canDefault && (present ? isMap(child) : required.has(name));
+                visit(candidate, keys, labels, depth + 1, canDescend);
+            }
+        }
+    };
+    if (schema)
+        visit(schema, base, [], 0, true);
+    else
+        lines.push('No options schema is installed; consult the plugin documentation.');
+    const node = document.getIn(base, true);
+    if (isNode(node)) {
+        const marker = '[dokebi:' + id + ']';
+        if (!node.commentBefore?.includes(marker))
+            node.commentBefore =
+                (node.commentBefore ? node.commentBefore + '\n' : '') + marker + '\n' + lines.join('\n');
+    }
+    const result = renderConfig(document);
+    parseProjectConfig(result);
+    return result;
+}

package/dist/configuration.d.ts

@@ -0,0 +1,19 @@
+import { type Document } from 'yaml';
+import { type ProjectConfig } from './project-state.js';
+export declare const CONFIG_FILE = "dokebi.yaml";
+export declare const LEGACY_CONFIG_FILE = "dokebi.json";
+export declare const CONFIG_BACKUP = ".dokebi/dokebi.json.backup";
+export declare const CONFIG_EXAMPLE = "# Copy to dokebi.yaml and keep actual credentials out of Git.\nschemaVersion: 1\noptions: {}\n";
+/** The real dokebi.yaml written by init: same shape, its own header. */
+export declare const CONFIG_TEMPLATE = "# Settings for this machine. Not committed to Git; dokebi.example.yaml is the shared sample.\nschemaVersion: 1\noptions: {}\n";
+/**
+ * Serializes a configuration document edited by the CLI. Non-empty mappings and sequences under
+ * `options` are written in block style, so schema comments and values stay readable even when the
+ * file started from `options: {}`. Values are unchanged; only the layout is normalized.
+ */
+export declare function renderConfig(document: Document): string;
+export declare const CONFIG_IGNORES: string[];
+export declare function parseProjectConfig(source: string): ProjectConfig;
+export declare function addConfigSection(source: string, id: string): string;
+export declare function migrateConfig(source: string): string;
+export declare function ignoreConfig(source: string): string;

package/dist/configuration.js

@@ -0,0 +1,84 @@
+import { ConfigError, parseConfig } from '@dokebi/config';
+import { isMap, parseDocument, stringify, visit } from 'yaml';
+import { CliError } from './errors.js';
+import { readConfig } from './project-state.js';
+export const CONFIG_FILE = 'dokebi.yaml';
+export const LEGACY_CONFIG_FILE = 'dokebi.json';
+export const CONFIG_BACKUP = '.dokebi/dokebi.json.backup';
+export const CONFIG_EXAMPLE = '# Copy to dokebi.yaml and keep actual credentials out of Git.\nschemaVersion: 1\noptions: {}\n';
+/** The real dokebi.yaml written by init: same shape, its own header. */
+export const CONFIG_TEMPLATE = '# Settings for this machine. Not committed to Git; dokebi.example.yaml is the shared sample.\nschemaVersion: 1\noptions: {}\n';
+/**
+ * Serializes a configuration document edited by the CLI. Non-empty mappings and sequences under
+ * `options` are written in block style, so schema comments and values stay readable even when the
+ * file started from `options: {}`. Values are unchanged; only the layout is normalized.
+ */
+export function renderConfig(document) {
+    const options = document.get('options', true);
+    if (isMap(options)) {
+        visit(options, {
+            Map(_, node) {
+                if (node.items.length)
+                    node.flow = false;
+            },
+            Seq(_, node) {
+                if (node.items.length)
+                    node.flow = false;
+            },
+        });
+        options.flow = false;
+    }
+    return document.toString();
+}
+export const CONFIG_IGNORES = ['dokebi.yaml', 'dokebi.json', '.dokebi/dokebi.json.backup'];
+export function parseProjectConfig(source) {
+    try {
+        return readConfig(parseConfig(source));
+    }
+    catch (cause) {
+        if (cause instanceof ConfigError) {
+            throw new CliError('INVALID_CONFIG', 'Invalid dokebi.yaml; inspect configuration syntax and schema', {
+                details: {
+                    code: cause.code,
+                    line: cause.line ?? null,
+                    column: cause.column ?? null,
+                    issues: cause.issues,
+                },
+            });
+        }
+        throw new CliError('INVALID_CONFIG', 'Invalid dokebi.yaml; inspect configuration syntax and schema');
+    }
+}
+// Parse through the runtime boundary first; AST edits only add missing sections.
+export function addConfigSection(source, id) {
+    const config = parseProjectConfig(source);
+    if (Object.hasOwn(config.options, id))
+        return source;
+    const document = parseDocument(source, { version: '1.2' });
+    document.setIn(['options', id], {});
+    const node = document.getIn(['options', id], true);
+    if (node && typeof node === 'object' && 'commentBefore' in node)
+        node.commentBefore =
+            ' Configure this plugin using its installed options schema and documentation.';
+    return renderConfig(document);
+}
+export function migrateConfig(source) {
+    let value;
+    try {
+        value = JSON.parse(source);
+    }
+    catch (cause) {
+        throw new CliError('INVALID_CONFIG', 'Invalid legacy JSON configuration', { cause });
+    }
+    readConfig(value);
+    const yaml = stringify(value);
+    parseProjectConfig(yaml);
+    return yaml;
+}
+export function ignoreConfig(source) {
+    const lines = new Set(source.split(/\r?\n/));
+    const missing = CONFIG_IGNORES.filter((entry) => !lines.has(entry));
+    return missing.length
+        ? source + (source && !source.endsWith('\n') ? '\n' : '') + missing.join('\n') + '\n'
+        : source;
+}

package/dist/errors.d.ts

@@ -1,8 +1,10 @@
 export interface CliErrorOptions extends ErrorOptions {
     details?: unknown;
+    phase?: 'arguments' | 'install' | 'commit' | 'unknown';
 }
 export declare class CliError extends Error {
     readonly code: string;
     constructor(code: string, message: string, options?: CliErrorOptions);
     readonly details: unknown;
+    readonly phase: CliErrorOptions['phase'];
 }

package/dist/errors.js

@@ -1,11 +1,12 @@
 export class CliError extends Error {
     code;
-    // [AI:수정] 저장소의 TypeScript 포맷과 import 순서 규칙을 적용한다.
     constructor(code, message, options) {
         super(message, options);
         this.code = code;
         this.name = 'CliError';
         this.details = options?.details;
+        this.phase = options?.phase;
     }
     details;
+    phase;
 }

package/dist/example-config.d.ts

@@ -0,0 +1,11 @@
+import type { ConfigChange } from './plugin-lifecycle.js';
+/**
+ * Updates dokebi.example.yaml for one plugin from its manifest defaults, configuration
+ * changes and schema guidance. Values from the real dokebi.yaml are never copied.
+ */
+export declare function syncExample(source: string, id: string, update: {
+    readonly defaults?: readonly Record<string, unknown>[];
+    readonly changes?: readonly ConfigChange[];
+    readonly schema?: Record<string, unknown> | null;
+}): string;
+export declare function markExampleRemoved(source: string, id: string): string;

package/dist/example-config.js

@@ -0,0 +1,16 @@
+import { applyConfigChanges, markRemoved } from './config-edit.js';
+import { scaffoldConfig } from './configuration-scaffold.js';
+import { mergeInstallDefaults } from './merge-install-defaults.js';
+/**
+ * Updates dokebi.example.yaml for one plugin from its manifest defaults, configuration
+ * changes and schema guidance. Values from the real dokebi.yaml are never copied.
+ */
+export function syncExample(source, id, update) {
+    let result = applyConfigChanges(source, id, update.changes ?? []);
+    for (const defaults of update.defaults ?? [])
+        result = mergeInstallDefaults(result, id, defaults);
+    return scaffoldConfig(result, id, update.schema ?? null);
+}
+export function markExampleRemoved(source, id) {
+    return markRemoved(source, id).source;
+}

package/dist/filesystem.js

@@ -1,9 +1,6 @@
-// [AI:수정] 공통 함수 공개 API를 hash와 path 카테고리로 나눠 탐색성과 유지보수성을 높인다.
-import { hash as hashing, path as paths } from '@dokebi/core/libraries';
-// [AI:삭제] 타입 명시와 경로 제어 문자 검증을 유지하면서 저장소 검사 규칙을 충족한다.
-// [AI:수정] 저장소의 TypeScript 포맷과 import 순서 규칙을 적용한다.
-import { lstat, readFile } from 'node:fs/promises';
+import { lstat } from 'node:fs/promises';
 import { join } from 'node:path';
+import { hash as hashing, path as paths } from '@dokebi/core/libraries';
 import { CliError } from './errors.js';
 export const hash = hashing.sha256;
 export const json = (value) => JSON.stringify(value, null, 2) + '\n';
@@ -13,7 +10,12 @@ export function relativePath(path) {
 }
 export function templateTarget(path) {
     relativePath(path);
-    if (!path.startsWith('src/') || path === 'src/main.ts' || path === 'src/dokebi.generated.ts') {
+    const key = paths.portablePathKey(path);
+    if (!path.startsWith('src/') ||
+        key === 'src/main.ts' ||
+        key.startsWith('src/main.ts/') ||
+        key === 'src/dokebi.generated.ts' ||
+        key.startsWith('src/dokebi.generated.ts/')) {
         throw new CliError('UNSAFE_PATH', `Template target is reserved: ${path}`);
     }
 }
@@ -59,7 +61,7 @@ export async function fingerprint(path) {
         return `directory:${stat.ino}:${stat.mtimeMs}`;
     if (!stat.isFile())
         throw new CliError('UNSAFE_PATH', 'Only regular files are supported');
-    return hashing.sha256(await readFile(path));
+    return hashing.sha256File(path);
 }
 export function object(value, label) {
     if (!value || typeof value !== 'object' || Array.isArray(value))

package/dist/generator.d.ts

@@ -1,3 +1,13 @@
 import type { PluginManifest } from './manifest.js';
-export declare function generateRegistration(plugins: PluginManifest[]): string;
-export declare const 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";
+import type { Installation } from './project-state.js';
+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. */
+export declare const MAIN_SOURCE_V1 = "import { Application, loadConfig } from '@dokebi/core';\nimport { registerPlugins } from './dokebi.generated.ts';\n\nconst document = await loadConfig(new URL('../dokebi.yaml', import.meta.url));\nconst app = new Application({ config: document.options });\nawait registerPlugins(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";
+export declare const MAIN_SOURCE = "import { Application, loadConfig } from '@dokebi/core';\nimport { registerPlugins } from './dokebi.generated.ts';\n\nconst document = await loadConfig(new URL('../dokebi.yaml', import.meta.url));\nconst app = new Application({ config: document.options });\nawait registerPlugins(app);\nawait app.start();\napp.logger.log('info', 'Dokebi application started');\n\n// The app runs until SIGINT/SIGTERM (servers, consumers) or until nothing is left to run\n// (one-off work), then drains and cleans up once. A second Ctrl+C exits immediately.\nlet stopping: Promise<void> | undefined;\nconst stop = (reason: string) =>\n  (stopping ??= app.stop().then(\n    () => app.logger.log('info', 'Dokebi application stopped', { reason }),\n    () => {\n      process.exitCode = 1;\n      app.logger.log('error', 'Dokebi application did not stop cleanly', { reason });\n    },\n  ));\nprocess.once('SIGINT', () => void stop('SIGINT'));\nprocess.once('SIGTERM', () => void stop('SIGTERM'));\nprocess.once('beforeExit', () => void stop('idle'));\n";
+/**
+ * tsconfig.json written by init. `node src/main.ts` strips types without compiling, so the
+ * editor and `tsc` should reject syntax Node cannot run (erasableSyntaxOnly) and need explicit
+ * `.ts` imports and `import type` (allowImportingTsExtensions, verbatimModuleSyntax).
+ */
+export declare const TSCONFIG_SOURCE: string;

package/dist/generator.js

@@ -1,33 +1,120 @@
-export function generateRegistration(plugins) {
-    // [AI:수정] 저장소의 TypeScript 포맷과 import 순서 규칙을 적용한다.
-    const imports = plugins.map((plugin, index) => `import { createPlugin as factory${index} } from ${JSON.stringify(plugin.packageName)};`);
-    const declarations = plugins.map((plugin, index) => {
-        const deps = plugin.dependencies.map((dependency) => `${JSON.stringify(dependency.name)}: instances[${JSON.stringify(dependency.name)}]`);
-        // [AI:수정] 생성 프로젝트의 빈 JSON 옵션도 플러그인 ID로 타입 안전하게 조회하도록 한다.
-        return `  const plugin${index} = factory${index}({ options: options[${JSON.stringify(plugin.id)}] ?? {}, dependencies: { ${deps.join(', ')} } });
-  if (plugin${index}.metadata.name !== ${JSON.stringify(plugin.id)} || plugin${index}.metadata.version !== ${JSON.stringify(plugin.version)}) {
-    throw new Error('Plugin runtime identity differs from installed manifest');
-  }
-  instances[${JSON.stringify(plugin.id)}] = plugin${index};
-  app.register(plugin${index});`;
+/** Import specifier of a user entry file, relative to src/dokebi.generated.ts. */
+function entrySpecifier(target) {
+    return './' + target.slice('src/'.length);
+}
+export function generateRegistration(plugins, installations = {}, apps = [], modules = []) {
+    const imports = [];
+    const factories = [];
+    plugins.forEach((plugin, index) => {
+        imports.push(`import { createPlugin as factory${index} } from ${JSON.stringify(plugin.packageName)};`);
+        const entry = installations[plugin.id]?.entry;
+        if (entry)
+            imports.push(`import * as entry${index} from ${JSON.stringify(entrySpecifier(entry))};`);
+        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') {
+            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(', ')} } }`;
+        }
+        // dokebi-module 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) {
+            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(', ')}] }`;
+        }
+        factories.push(`    factory${index}({ app: app.view, options: optionsOf(${JSON.stringify(plugin.id)})${entryCode} }),`);
     });
-    return `// Generated by dokebi. Change dokebi.json options instead of this file.
-import type { Application, Plugin } from '@dokebi/core';
-import config from '../dokebi.json' with { type: 'json' };
+    // Plugins with an entry may receive user-chosen dependencies (for example web requires),
+    // so only plugins without an entry are held to their manifest dependency list.
+    const manifests = plugins.map((plugin) => ({
+        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,
+    }));
+    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';
 ${imports.join('\n')}
 
-export function registerPlugins(app: Application): void {
-  const options: Record<string, unknown> = config.options;
-  const instances: Record<string, Plugin<unknown>> = Object.create(null);
-${declarations.join('\n')}
+const MANIFESTS: readonly {
+  id: string;
+  version: string;
+  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;
+  }
+}
+
+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')}
+  ];
+  for (const [index, plugin] of plugins.entries()) {
+    const manifest = MANIFESTS[index];
+    if (!manifest || plugin.metadata.name !== manifest.id || plugin.metadata.version !== manifest.version)
+      throw new Error('Plugin runtime identity differs from installed manifest');
+    for (const dependency of plugin.metadata.dependencies ?? [])
+      if (!manifest.entry && !manifest.dependencies.includes(dependency.name))
+        throw new Error('Plugin runtime dependency is not declared in its manifest: ' + manifest.id);
+    app.register(plugin);
+  }
 }
 `;
 }
-export const MAIN_SOURCE = `import { Application } from '@dokebi/core';
+export 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. */
+export const MAIN_SOURCE_V1 = `import { Application, loadConfig } from '@dokebi/core';
 import { registerPlugins } from './dokebi.generated.ts';
 
-const app = new Application();
-registerPlugins(app);
+const document = await loadConfig(new URL('../dokebi.yaml', import.meta.url));
+const app = new Application({ config: document.options });
+await registerPlugins(app);
 await app.start();
 try {
   app.logger.log('info', 'Dokebi application started');
@@ -36,3 +123,46 @@ try {
   await app.stop();
 }
 `;
+export const MAIN_SOURCE = `import { Application, loadConfig } from '@dokebi/core';
+import { registerPlugins } from './dokebi.generated.ts';
+
+const document = await loadConfig(new URL('../dokebi.yaml', import.meta.url));
+const app = new Application({ config: document.options });
+await registerPlugins(app);
+await app.start();
+app.logger.log('info', 'Dokebi application started');
+
+// The app runs until SIGINT/SIGTERM (servers, consumers) or until nothing is left to run
+// (one-off work), then drains and cleans up once. A second Ctrl+C exits immediately.
+let stopping: Promise<void> | undefined;
+const stop = (reason: string) =>
+  (stopping ??= app.stop().then(
+    () => app.logger.log('info', 'Dokebi application stopped', { reason }),
+    () => {
+      process.exitCode = 1;
+      app.logger.log('error', 'Dokebi application did not stop cleanly', { reason });
+    },
+  ));
+process.once('SIGINT', () => void stop('SIGINT'));
+process.once('SIGTERM', () => void stop('SIGTERM'));
+process.once('beforeExit', () => void stop('idle'));
+`;
+/**
+ * tsconfig.json written by init. `node src/main.ts` strips types without compiling, so the
+ * editor and `tsc` should reject syntax Node cannot run (erasableSyntaxOnly) and need explicit
+ * `.ts` imports and `import type` (allowImportingTsExtensions, verbatimModuleSyntax).
+ */
+export const TSCONFIG_SOURCE = `${JSON.stringify({
+    compilerOptions: {
+        target: 'ES2023',
+        module: 'NodeNext',
+        moduleResolution: 'NodeNext',
+        strict: true,
+        noEmit: true,
+        allowImportingTsExtensions: true,
+        erasableSyntaxOnly: true,
+        verbatimModuleSyntax: true,
+        skipLibCheck: true,
+    },
+    include: ['src/**/*.ts'],
+}, null, 2)}\n`;

package/dist/install-module.d.ts

@@ -0,0 +1,23 @@
+export type InstallPhase = 'planInstall' | 'planUpgrade' | 'check';
+export interface InstallModuleContext {
+    readonly options: Readonly<Record<string, unknown>>;
+    readonly plugins: readonly {
+        readonly id: string;
+        readonly version: string;
+        readonly packageName: string;
+    }[];
+    readonly [key: string]: unknown;
+}
+export declare class InstallPlanningError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+/** Returned when the module does not export the requested phase. */
+export declare const PHASE_MISSING: unique symbol;
+/**
+ * Runs one lifecycle phase of a plugin installation module in a child process.
+ * The child uses the Node permission model: it may read only `readRoots`
+ * (real paths), cannot write files or spawn processes, and receives no
+ * parent environment variables. Node 24 does not restrict network access.
+ */
+export declare function runInstallModule(modulePath: string, phase: InstallPhase, context: InstallModuleContext, readRoots?: readonly string[]): Promise<unknown>;