@dokebi/cli 0.1.0 → 0.2.0

package/dist/npm-client.js

@@ -1,18 +1,14 @@
-// [AI:생성] 설치 중 플러그인 코드를 실행하지 않고 실제 인스턴스로 의존 플러그인을 연결한다.
 import { spawn } from 'node:child_process';
-import { readFile, writeFile } from 'node:fs/promises';
+import { readdir, readFile, writeFile } from 'node:fs/promises';
 import { isAbsolute, resolve } from 'node:path';
 import { CliError } from './errors.js';
 import { json, object, parseObject } from './filesystem.js';
 import { PACKAGE_NAME } from './manifest.js';
-// [AI:수정] 패키지와 lockfile 구조에 맞는 경로 정규화로 데이터 변형 원인을 제거한다.
 import { normalizeLockPaths, normalizePackagePaths } from './npm-paths.js';
 export function packageSpec(spec, cwd) {
     if (spec.endsWith('.tgz'))
         return `file:${resolve(cwd, spec.replace(/^file:/, ''))}`;
-    // [AI:수정] 저장소의 TypeScript 포맷과 import 순서 규칙을 적용한다.
     const match = /^((?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*)(?:@([a-zA-Z0-9.*^~<>=| -]+))?$/.exec(spec);
-    // [AI:수정] 타입 명시와 경로 제어 문자 검증을 유지하면서 저장소 검사 규칙을 충족한다.
     if (!match?.[1] || !PACKAGE_NAME.test(match[1]))
         throw new CliError('INVALID_SPEC', 'Use a registry package or local .tgz');
     return spec;
@@ -34,7 +30,6 @@ export function validateProjectPackage(pkg) {
             if (typeof value !== 'string' ||
                 value.startsWith('workspace:') ||
                 value.startsWith('link:') ||
-                // [AI:수정] 문서의 지원 범위대로 git·URL·디렉터리 의존성을 변경 전에 거부한다.
                 (value.startsWith('file:')
                     ? !isAbsolute(value.slice(5)) || !value.endsWith('.tgz')
                     : !/^[a-zA-Z0-9.*^~<>=| -]+$/.test(value))) {
@@ -44,11 +39,9 @@ export function validateProjectPackage(pkg) {
     }
 }
 export class NpmClient {
+    /** Installs into a standalone directory (the project or the CLI's staging). */
     async install(directory, spec) {
-        const npmScript = process.env.npm_execpath;
-        const command = npmScript?.endsWith('npm-cli.js') ? process.execPath : 'npm';
-        const args = [
-            ...(npmScript?.endsWith('npm-cli.js') ? [npmScript] : []),
+        await this.#run(directory, [
             'install',
             ...(spec ? [spec] : []),
             '--ignore-scripts',
@@ -57,9 +50,38 @@ export class NpmClient {
             '--no-fund',
             '--workspaces=false',
             '--package-lock=true',
-        ];
+        ]);
+        for (const file of ['package.json', 'package-lock.json']) {
+            const content = parseObject(await readFile(resolve(directory, file), 'utf8'), file);
+            if (file === 'package.json')
+                normalizePackagePaths(content, directory);
+            else
+                normalizeLockPaths(content, directory);
+            await writeFile(resolve(directory, file), json(content));
+        }
+    }
+    /** `npm pack` of a workspace package into `destination`; returns the archive path (D-0035). */
+    async pack(directory, destination) {
+        const before = new Set(await readdir(destination));
+        await this.#run(directory, ['pack', '--ignore-scripts', '--pack-destination', destination]);
+        const created = (await readdir(destination)).filter((name) => !before.has(name) && name.endsWith('.tgz'));
+        if (created.length !== 1)
+            throw new CliError('NPM_FAILED', 'npm pack created no archive');
+        return resolve(destination, created[0]);
+    }
+    /** `npm install` at a workspace root: brings its lock and node_modules in line (D-0035). */
+    async installWorkspace(root) {
+        await this.#run(root, ['install', '--ignore-scripts', '--no-audit', '--no-fund']);
+    }
+    async #run(directory, npmArgs) {
+        const npmScript = process.env.npm_execpath;
+        const command = npmScript?.endsWith('npm-cli.js') ? process.execPath : 'npm';
+        const args = [...(npmScript?.endsWith('npm-cli.js') ? [npmScript] : []), ...npmArgs];
         await new Promise((resolvePromise, reject) => {
-            const child = spawn(command, args, { cwd: directory, stdio: 'ignore' });
+            const child = spawn(command, args, {
+                cwd: directory,
+                stdio: 'ignore',
+            });
             let timedOut = false;
             const timer = setTimeout(() => {
                 timedOut = true;
@@ -77,13 +99,5 @@ export class NpmClient {
                     reject(new CliError('NPM_FAILED', timedOut ? 'npm timed out' : `npm failed with exit code ${code}`));
             });
         });
-        for (const file of ['package.json', 'package-lock.json']) {
-            const content = parseObject(await readFile(resolve(directory, file), 'utf8'), file);
-            if (file === 'package.json')
-                normalizePackagePaths(content, directory);
-            else
-                normalizeLockPaths(content, directory);
-            await writeFile(resolve(directory, file), json(content));
-        }
     }
 }

package/dist/npm-paths.js

@@ -1,8 +1,6 @@
-// [AI:생성] 사용자 데이터를 재귀 순회하지 않고 npm 경로 필드만 보정한다.
 import { resolve } from 'node:path';
 import { object } from './filesystem.js';
 const DEPENDENCY_FIELDS = [
-    // [AI:수정] 데이터 보존 수정과 회귀 테스트에 저장소 포맷을 적용한다.
     'dependencies',
     'devDependencies',
     'optionalDependencies',

package/dist/output.d.ts

@@ -1,3 +1,3 @@
-export declare const CLI_VERSION = "0.1.0";
+export declare const CLI_VERSION = "0.2.0";
 export declare function envelope(command: string, result: unknown, ok?: boolean): object;
 export declare function failure(command: string, error: unknown, mutationStarted: boolean): object;

package/dist/output.js

@@ -1,12 +1,10 @@
-// [AI:생성] JSON 응답 버전과 오류·변경 상태를 안정적인 계약으로 제공한다.
 import { CliError } from './errors.js';
-export const CLI_VERSION = '0.1.0';
+export const CLI_VERSION = '0.2.0';
 export function envelope(command, result, ok = true) {
     return { schemaVersion: 1, cliVersion: CLI_VERSION, command, ok, result, error: null };
 }
 export function failure(command, error, mutationStarted) {
     const code = error instanceof CliError ? error.code : 'INTERNAL_ERROR';
-    // [AI:수정] CLI 진단·스키마·회귀 검증의 포맷과 import 순서를 맞춘다.
     const mutation = !mutationStarted
         ? 'none'
         : code === 'COMMIT_FAILED'
@@ -14,13 +12,14 @@ export function failure(command, error, mutationStarted) {
             : code === 'RECOVERY_REQUIRED'
                 ? 'recovery-required'
                 : 'unknown';
-    const phase = code === 'NPM_FAILED'
-        ? 'install'
-        : ['COMMIT_FAILED', 'RECOVERY_REQUIRED', 'CONCURRENT_CHANGE'].includes(code)
-            ? 'commit'
-            : code === 'USAGE'
-                ? 'arguments'
-                : 'unknown';
+    const phase = (error instanceof CliError ? error.phase : undefined) ??
+        (code === 'NPM_FAILED'
+            ? 'install'
+            : ['COMMIT_FAILED', 'RECOVERY_REQUIRED', 'CONCURRENT_CHANGE'].includes(code)
+                ? 'commit'
+                : code === 'USAGE'
+                    ? 'arguments'
+                    : 'unknown');
     return {
         schemaVersion: 1,
         cliVersion: CLI_VERSION,

package/dist/plugin-lifecycle.d.ts

@@ -0,0 +1,43 @@
+import { type InstallPlan } from './install-plan.js';
+import { type PluginManifest } from './manifest.js';
+import type { Installation } from './project-state.js';
+export interface ConfigChange {
+    op: 'rename' | 'remove' | 'default';
+    from?: string[];
+    to?: string[];
+    path?: string[];
+    value?: unknown;
+}
+export interface LifecyclePlan extends Omit<InstallPlan, 'configDefaults'> {
+    /** Static defaults first, then module defaults; each only fills missing values. */
+    defaults: Record<string, unknown>[];
+    requires: string[];
+    configChanges: ConfigChange[];
+}
+export interface CheckDiagnostic {
+    code: string;
+    severity: 'error' | 'warning';
+    optionPath?: string[];
+    /** One-line next step for the developer, such as an install command. */
+    hint?: string;
+}
+export interface CheckResult {
+    requires: string[];
+    diagnostics: CheckDiagnostic[];
+}
+export interface LifecycleInput {
+    /** Directory whose node_modules contains the plugin package (project root or staging). */
+    readonly base: string;
+    readonly plugin: PluginManifest;
+    readonly options: Record<string, unknown>;
+    readonly plugins: readonly PluginManifest[];
+    readonly projectPackages: readonly string[];
+    readonly installation?: Installation;
+}
+export declare function optionsOf(options: Record<string, unknown>, id: string): Record<string, unknown>;
+export declare function optionPath(value: unknown): string[];
+/** Static `dokebi.install` merged with the module's planInstall or planUpgrade result. */
+export declare function planLifecycle(input: LifecycleInput, phase: 'planInstall' | 'planUpgrade', extra?: Record<string, unknown>): Promise<LifecyclePlan>;
+export declare function checkPlugin(input: LifecycleInput): Promise<CheckResult>;
+/** Runs check for every plugin and returns results by plugin id. */
+export declare function checkAll(inputs: readonly Omit<LifecycleInput, 'plugins'>[], plugins: readonly PluginManifest[]): Promise<Map<string, CheckResult>>;

package/dist/plugin-lifecycle.js

@@ -0,0 +1,194 @@
+import { realpath } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CliError } from './errors.js';
+import { object } from './filesystem.js';
+import { InstallPlanningError, PHASE_MISSING, runInstallModule, } from './install-module.js';
+import { readInstallPlan } from './install-plan.js';
+import { assertLayout } from './layout.js';
+import { ID } from './manifest.js';
+import { packageFile, workspaceRootOf } from './workspace.js';
+// Printable single line: no control characters (log/terminal injection) and a short bound.
+const HINT = /^[^\p{Cc}]{1,200}$/u;
+const CODE = /^[A-Z][A-Z0-9_]{0,63}$/;
+const KEY = /^[A-Za-z0-9_-]{1,64}$/;
+export function optionsOf(options, id) {
+    const value = Object.hasOwn(options, id) ? options[id] : undefined;
+    return value === undefined || value === null ? {} : object(value, 'plugin options');
+}
+function requirements(value, self) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error('requires');
+    const result = [];
+    for (const item of value) {
+        if (typeof item !== 'string' || !ID.test(item) || item === self || result.includes(item))
+            throw new Error('requires');
+        result.push(item);
+    }
+    return result;
+}
+export function optionPath(value) {
+    if (!Array.isArray(value) || value.length === 0 || value.length > 16)
+        throw new Error('path');
+    for (const key of value) {
+        if (typeof key !== 'string' || !KEY.test(key))
+            throw new Error('path');
+        if (['__proto__', 'constructor', 'prototype'].includes(key))
+            throw new Error('path');
+    }
+    return [...value];
+}
+function configChanges(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error('configChanges');
+    return value.map((raw) => {
+        const change = object(raw, 'config change');
+        const keys = Object.keys(change);
+        if (change.op === 'rename' && keys.every((key) => ['op', 'from', 'to'].includes(key)))
+            return { op: 'rename', from: optionPath(change.from), to: optionPath(change.to) };
+        if (change.op === 'remove' && keys.every((key) => ['op', 'path'].includes(key)))
+            return { op: 'remove', path: optionPath(change.path) };
+        if (change.op === 'default' && keys.every((key) => ['op', 'path', 'value'].includes(key)))
+            return { op: 'default', path: optionPath(change.path), value: change.value };
+        throw new Error('configChanges');
+    });
+}
+async function run(input, phase, extra = {}) {
+    const modulePath = input.plugin.installModule;
+    if (!modulePath)
+        return PHASE_MISSING;
+    const path = await packageFile(input.base, input.plugin.packageName, modulePath);
+    // A workspace member's packages live anywhere below the workspace root (D-0035).
+    const workspace = await workspaceRootOf(input.base);
+    const nodeModules = await realpath(workspace ?? join(input.base, 'node_modules'));
+    try {
+        return await runInstallModule(path, phase, {
+            options: optionsOf(input.options, input.plugin.id),
+            plugins: input.plugins.map(({ id, version, packageName }) => ({
+                id,
+                version,
+                packageName,
+            })),
+            projectPackages: [...input.projectPackages],
+            ...extra,
+        }, [nodeModules]);
+    }
+    catch (error) {
+        throw new CliError('PLUGIN_INSTALL_FAILED', input.plugin.id +
+            ': ' +
+            (error instanceof InstallPlanningError ? error.code : 'INSTALL_MODULE_FAILED'), { details: { plugin: input.plugin.id, phase } });
+    }
+}
+function invalidPlan(id) {
+    return new CliError('INVALID_MANIFEST', 'Invalid installation plan: ' + id);
+}
+/** Static `dokebi.install` merged with the module's planInstall or planUpgrade result. */
+export async function planLifecycle(input, phase, extra = {}) {
+    const raw = await run(input, phase, extra);
+    const plugin = input.plugin;
+    const base = {
+        files: plugin.files,
+        ...(plugin.directories ? { directories: plugin.directories } : {}),
+        ...(plugin.entry ? { entry: plugin.entry } : {}),
+        ...(plugin.configDefaults ? { configDefaults: plugin.configDefaults } : {}),
+    };
+    const staticDefaults = base.configDefaults ? [base.configDefaults] : [];
+    if (raw === PHASE_MISSING) {
+        const { configDefaults: _ignored, ...rest } = base;
+        return { ...rest, defaults: staticDefaults, requires: [], configChanges: [] };
+    }
+    let plan;
+    let requires;
+    let changes;
+    try {
+        plan = object(raw, 'installation plan');
+        const allowed = phase === 'planInstall'
+            ? ['directories', 'files', 'entry', 'configDefaults', 'requires']
+            : ['directories', 'files', 'entry', 'configChanges', 'requires'];
+        if (Object.keys(plan).some((key) => !allowed.includes(key)))
+            throw new Error('keys');
+        requires = requirements(plan.requires, plugin.id);
+        changes = configChanges(plan.configChanges);
+    }
+    catch {
+        throw invalidPlan(plugin.id);
+    }
+    if (plan.entry !== undefined && base.entry !== undefined)
+        throw invalidPlan(plugin.id);
+    const dynamic = readInstallPlan({
+        ...(plan.files === undefined ? {} : { files: plan.files }),
+        directories: [...(base.directories ?? []), ...(plan.directories ?? [])],
+        ...(plan.entry !== undefined
+            ? { entry: plan.entry }
+            : base.entry
+                ? { entry: base.entry }
+                : {}),
+        ...(plan.configDefaults === undefined ? {} : { configDefaults: plan.configDefaults }),
+    }, base.files);
+    // Files and folders an install module adds follow the same layout as the manifest (D-0031).
+    try {
+        assertLayout({
+            files: dynamic.files.slice(base.files.length),
+            directories: plan.directories ?? [],
+            ...(plan.entry !== undefined ? { entry: dynamic.entry } : {}),
+        }, plugin.id);
+    }
+    catch {
+        throw invalidPlan(plugin.id);
+    }
+    const { configDefaults, ...files } = dynamic;
+    return {
+        ...files,
+        defaults: configDefaults ? [...staticDefaults, configDefaults] : staticDefaults,
+        requires,
+        configChanges: changes,
+    };
+}
+export async function checkPlugin(input) {
+    const raw = await run(input, 'check', {
+        installation: input.installation?.entry ? { entry: input.installation.entry } : {},
+    });
+    if (raw === PHASE_MISSING)
+        return { requires: [], diagnostics: [] };
+    try {
+        const result = object(raw, 'check result');
+        if (Object.keys(result).some((key) => key !== 'requires' && key !== 'diagnostics'))
+            throw new Error('keys');
+        const diagnostics = [];
+        if (result.diagnostics !== undefined) {
+            if (!Array.isArray(result.diagnostics) || result.diagnostics.length > 100)
+                throw new Error('diagnostics');
+            for (const raw of result.diagnostics) {
+                const item = object(raw, 'diagnostic');
+                if (Object.keys(item).some((key) => !['code', 'severity', 'optionPath', 'hint'].includes(key)) ||
+                    typeof item.code !== 'string' ||
+                    !CODE.test(item.code) ||
+                    (item.severity !== 'error' && item.severity !== 'warning') ||
+                    (item.hint !== undefined && (typeof item.hint !== 'string' || !HINT.test(item.hint))))
+                    throw new Error('diagnostic');
+                diagnostics.push({
+                    code: item.code,
+                    severity: item.severity,
+                    ...(item.optionPath === undefined ? {} : { optionPath: optionPath(item.optionPath) }),
+                    ...(item.hint === undefined ? {} : { hint: item.hint }),
+                });
+            }
+        }
+        return { requires: requirements(result.requires, input.plugin.id), diagnostics };
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        throw new CliError('INVALID_MANIFEST', 'Invalid check result: ' + input.plugin.id);
+    }
+}
+/** Runs check for every plugin and returns results by plugin id. */
+export async function checkAll(inputs, plugins) {
+    const results = new Map();
+    for (const input of inputs)
+        results.set(input.plugin.id, await checkPlugin({ ...input, plugins }));
+    return results;
+}

package/dist/plugin-options.d.ts

@@ -6,5 +6,12 @@ export interface OptionsCheck {
         keyword: string;
     }>;
 }
+export declare class PluginOptionsValidator {
+    #private;
+    constructor(options?: {
+        allErrors?: boolean;
+    });
+    check(root: string, plugin: PluginManifest, options: unknown): Promise<OptionsCheck>;
+}
 export declare function checkPluginOptions(root: string, plugin: PluginManifest, options: unknown): Promise<OptionsCheck>;
 export declare function validatePluginOptions(root: string, plugins: PluginManifest[], options: Record<string, unknown>): Promise<void>;

package/dist/plugin-options.js

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

package/dist/project-guide.d.ts

@@ -1 +1 @@
-export declare const PROJECT_GUIDE = "# Dokebi \uD504\uB85C\uC81D\uD2B8 \uC791\uC5C5 \uC548\uB0B4\n\n\uC124\uCE58\uB41C \uCF54\uC5B4 \uACC4\uC57D\uC740 [\uCF54\uC5B4 AI \uC0AC\uC6A9 \uC548\uB0B4](node_modules/@dokebi/core/AI.md)\uB97C \uC77D\uB294\uB2E4.\n\uD328\uD0A4\uC9C0 \uBC84\uC804\uC740 package.json\uACFC \uC2E4\uC81C node_modules\uB97C \uD568\uAED8 \uD655\uC778\uD55C\uB2E4.\n\n- \uD504\uB85C\uC81D\uD2B8 \uB8E8\uD2B8\uC5D0\uC11C \uC124\uCE58\uB41C CLI\uB85C dokebi inspect --json, dokebi doctor --json\uC744 \uC2E4\uD589\uD55C\uB2E4.\n- inspect\uC5D0 \uB098\uC628 \uD50C\uB7EC\uADF8\uC778 documentation\uACFC optionsSchema\uB97C \uD655\uC778\uD55C\uB2E4.\n- src/main.ts\uB294 \uC0AC\uC6A9\uC790 \uC9C4\uC785\uC810, dokebi.json\uC740 \uC0AC\uC6A9\uC790 \uC635\uC158\uC774\uB2E4.\n- src/dokebi.generated.ts\uC640 .dokebi/state.json\uC740 \uC9C1\uC811 \uD3B8\uC9D1\uD558\uC9C0 \uC54A\uB294\uB2E4.\n- add\uB294 \uD328\uD0A4\uC9C0 \uC9C0\uC815, remove\uB294 \uD50C\uB7EC\uADF8\uC778 ID\uB97C \uBC1B\uB294\uB2E4. \uBA3C\uC800 --dry-run\uC73C\uB85C \uAC80\uD1A0\uD55C\uB2E4.\n- doctor\uB294 \uC790\uB3D9 \uBCF5\uAD6C\uD558\uC9C0 \uC54A\uB294\uB2E4. \uC7A0\uAE08\uC774\uB098 \uBC31\uC5C5\uC744 \uC784\uC758 \uC0AD\uC81C\uD558\uAC70\uB098 \uC2E4\uD328\uB97C \uBB34\uC870\uAC74 \uC7AC\uC2DC\uB3C4\uD558\uC9C0 \uC54A\uB294\uB2E4.\n- \uBCC0\uACBD \uD6C4 npm start\uC640 \uD504\uB85C\uC81D\uD2B8\uBCC4 \uD14C\uC2A4\uD2B8\uB97C \uC2E4\uD589\uD55C\uB2E4.\n";
+export declare const PROJECT_GUIDE = "# Dokebi \uD504\uB85C\uC81D\uD2B8 \uC791\uC5C5 \uC548\uB0B4\n\n\uC124\uCE58\uB41C \uCF54\uC5B4 \uACC4\uC57D\uC740 [\uCF54\uC5B4 AI \uC0AC\uC6A9 \uC548\uB0B4](node_modules/@dokebi/core/AI.md)\uB97C \uC77D\uB294\uB2E4.\n\uD328\uD0A4\uC9C0 \uBC84\uC804\uC740 package.json\uACFC \uC2E4\uC81C node_modules\uB97C \uD568\uAED8 \uD655\uC778\uD55C\uB2E4.\n\n- \uD504\uB85C\uC81D\uD2B8 \uB8E8\uD2B8\uC5D0\uC11C \uC124\uCE58\uB41C CLI\uB85C dokebi inspect --json, dokebi doctor --json\uC744 \uC2E4\uD589\uD55C\uB2E4.\n- inspect\uC5D0 \uB098\uC628 \uD50C\uB7EC\uADF8\uC778 documentation\uACFC optionsSchema\uB97C \uD655\uC778\uD55C\uB2E4.\n- src/main.ts\uB294 \uC0AC\uC6A9\uC790 \uC9C4\uC785\uC810, dokebi.yaml\uC740 \uC0AC\uC6A9\uC790 \uC635\uC158\uC774\uB2E4.\n- \uD3F4\uB354 \uAD6C\uC870(D-0031\u00B7D-0032): src/apps/<\uC571>(\uC571 \uD558\uB098\uC758 app.ts\u00B7routes.ts\u00B7controllers\u00B7models\u00B7views\u00B7sockets), src/shared/modules/<\uBAA8\uB4C8>(\uAE30\uB2A5 \uD558\uB098\uC758 module.ts\u00B7routes.ts\u00B7controllers\u00B7models\u00B7views, dokebi module add\uB85C \uB9CC\uB4E4\uACE0 \uC571\uC758 modules: { '/\uC811\uB450\uC0AC': \uBAA8\uB4C8 }\uB85C \uBD99\uC778\uB2E4), src/shared/models(\uACF5\uD1B5 \uC21C\uC218 \uCF54\uB4DC), src/shared/views(\uACF5\uD1B5 \uB808\uC774\uC544\uC6C3\u00B7\uBD80\uBD84 \uD15C\uD50C\uB9BF), src/infra/<\uC774\uB984>(\uD50C\uB7EC\uADF8\uC778 \uC5F0\uACB0 \uC124\uC815: db/connections.ts, events/types.ts, inertia/shared.ts, web/requires.ts, worker/tasks.ts), src/plugins/<\uC774\uB984>(\uC9C1\uC811 \uB9CC\uB4E0 \uD50C\uB7EC\uADF8\uC778). \uC5C5\uBB34 \uCF54\uB4DC\uB294 apps\u00B7shared/modules\uC5D0\uB9CC, \uD50C\uB7EC\uADF8\uC778 \uC5F0\uACB0 \uCF54\uB4DC\uB294 infra\uC5D0\uB9CC \uB454\uB2E4. \uCEE8\uD2B8\uB864\uB7EC\uB294 \uC571\uC774\uB098 \uBAA8\uB4C8\uC5D0 \uC18D\uD55C\uB2E4.\n- \uC2E4\uC81C dokebi.yaml\uC740 Git\uC5D0 \uB123\uC9C0 \uC54A\uB294\uB2E4. dokebi.example.yaml\uC740 \uBE44\uBC00\uAC12 \uC5C6\uB294 \uCD5C\uCD08 \uC124\uC815 \uACAC\uBCF8\uC774\uB2E4.\n- JSON \uD504\uB85C\uC81D\uD2B8\uB294 core 0.2.x \uC124\uCE58 \uD6C4 dokebi migrate --dry-run\uC73C\uB85C \uC774\uC804 \uACC4\uD68D\uBD80\uD130 \uD655\uC778\uD55C\uB2E4.\n- config\uB294 \uCF54\uC5B4 \uD544\uC218 \uAD6C\uC131\uC73C\uB85C \uC790\uB3D9 \uC124\uCE58\uB418\uBA70 remove\uD560 \uC218 \uC5C6\uB2E4.\n- src/dokebi.generated.ts\uC640 .dokebi/state.json\uC740 \uC9C1\uC811 \uD3B8\uC9D1\uD558\uC9C0 \uC54A\uB294\uB2E4.\n- add\uB294 \uD328\uD0A4\uC9C0 \uC9C0\uC815, upgrade\u00B7remove\uB294 \uD50C\uB7EC\uADF8\uC778 ID\uB97C \uBC1B\uB294\uB2E4. \uBA3C\uC800 --dry-run\uC73C\uB85C \uAC80\uD1A0\uD55C\uB2E4. \uC124\uCE58 \uC804 \uC124\uC815\uC740 add --set path=value\uB85C \uB118\uAE38 \uC218 \uC788\uB2E4.\n- \uD50C\uB7EC\uADF8\uC778\uC774 \uB9CC\uB4E0 \uC9C4\uC785 \uD30C\uC77C(\uC608: src/db/connections.ts)\uC740 \uC0AC\uC6A9\uC790 \uCF54\uB4DC\uB2E4. \uC9C1\uC811 \uACE0\uCE58\uACE0, \uC9C0\uC6B0\uC9C0 \uC54A\uB294\uB2E4.\n- doctor\uB294 \uC790\uB3D9 \uBCF5\uAD6C\uD558\uC9C0 \uC54A\uB294\uB2E4. \uC7A0\uAE08\uC774\uB098 \uBC31\uC5C5\uC744 \uC784\uC758 \uC0AD\uC81C\uD558\uAC70\uB098 \uC2E4\uD328\uB97C \uBB34\uC870\uAC74 \uC7AC\uC2DC\uB3C4\uD558\uC9C0 \uC54A\uB294\uB2E4.\n- src\uC758 .ts\uB294 Node\uAC00 \uD0C0\uC785\uB9CC \uC9C0\uC6B0\uACE0 \uC2E4\uD589\uD55C\uB2E4. \uC0DD\uC131\uC790 \uB9E4\uAC1C\uBCC0\uC218 \uC18D\uC131\u00B7enum\u00B7namespace\uCC98\uB7FC \uC9C0\uC6B8 \uC218 \uC5C6\uB294 \uBB38\uBC95\uC740 \uC4F0\uC9C0 \uC54A\uB294\uB2E4(tsconfig.json\uC758 erasableSyntaxOnly\uAC00 \uD3B8\uC9D1\uAE30\uC640 npx tsc -p tsconfig.json\uC5D0\uC11C \uC54C\uB824 \uC900\uB2E4).\n- \uBCC0\uACBD \uD6C4 npm start\uC640 \uD504\uB85C\uC81D\uD2B8\uBCC4 \uD14C\uC2A4\uD2B8\uB97C \uC2E4\uD589\uD55C\uB2E4.\n";

package/dist/project-guide.js

@@ -1,4 +1,3 @@
-// [AI:생성] 플러그인과 설치 버전의 사용 계약을 AI가 추측 없이 확인하게 한다.
 export const PROJECT_GUIDE = `# Dokebi 프로젝트 작업 안내
 
 설치된 코어 계약은 [코어 AI 사용 안내](node_modules/@dokebi/core/AI.md)를 읽는다.
@@ -6,9 +5,15 @@ export const PROJECT_GUIDE = `# Dokebi 프로젝트 작업 안내
 
 - 프로젝트 루트에서 설치된 CLI로 dokebi inspect --json, dokebi doctor --json을 실행한다.
 - inspect에 나온 플러그인 documentation과 optionsSchema를 확인한다.
-- src/main.ts는 사용자 진입점, dokebi.json은 사용자 옵션이다.
+- src/main.ts는 사용자 진입점, dokebi.yaml은 사용자 옵션이다.
+- 폴더 구조(D-0031·D-0032): src/apps/<앱>(앱 하나의 app.ts·routes.ts·controllers·models·views·sockets), src/shared/modules/<모듈>(기능 하나의 module.ts·routes.ts·controllers·models·views, dokebi module add로 만들고 앱의 modules: { '/접두사': 모듈 }로 붙인다), src/shared/models(공통 순수 코드), src/shared/views(공통 레이아웃·부분 템플릿), src/infra/<이름>(플러그인 연결 설정: db/connections.ts, events/types.ts, inertia/shared.ts, web/requires.ts, worker/tasks.ts), src/plugins/<이름>(직접 만든 플러그인). 업무 코드는 apps·shared/modules에만, 플러그인 연결 코드는 infra에만 둔다. 컨트롤러는 앱이나 모듈에 속한다.
+- 실제 dokebi.yaml은 Git에 넣지 않는다. dokebi.example.yaml은 비밀값 없는 최초 설정 견본이다.
+- JSON 프로젝트는 core 0.2.x 설치 후 dokebi migrate --dry-run으로 이전 계획부터 확인한다.
+- config는 코어 필수 구성으로 자동 설치되며 remove할 수 없다.
 - src/dokebi.generated.ts와 .dokebi/state.json은 직접 편집하지 않는다.
-- add는 패키지 지정, remove는 플러그인 ID를 받는다. 먼저 --dry-run으로 검토한다.
+- add는 패키지 지정, upgrade·remove는 플러그인 ID를 받는다. 먼저 --dry-run으로 검토한다. 설치 전 설정은 add --set path=value로 넘길 수 있다.
+- 플러그인이 만든 진입 파일(예: src/db/connections.ts)은 사용자 코드다. 직접 고치고, 지우지 않는다.
 - doctor는 자동 복구하지 않는다. 잠금이나 백업을 임의 삭제하거나 실패를 무조건 재시도하지 않는다.
+- src의 .ts는 Node가 타입만 지우고 실행한다. 생성자 매개변수 속성·enum·namespace처럼 지울 수 없는 문법은 쓰지 않는다(tsconfig.json의 erasableSyntaxOnly가 편집기와 npx tsc -p tsconfig.json에서 알려 준다).
 - 변경 후 npm start와 프로젝트별 테스트를 실행한다.
 `;

package/dist/project-inspector.d.ts

@@ -1,4 +1,6 @@
 import { type PluginManifest } from './manifest.js';
+import { type Installation } from './project-state.js';
+import { type RequiredPlugin } from './required-plugins.js';
 export interface Diagnostic {
     code: string;
     severity: 'error' | 'warning';
@@ -10,9 +12,11 @@ export interface Inspection {
     root: string;
     healthy: boolean;
     coreVersion: string | null;
+    requiredPlugins: RequiredPlugin[];
     plugins: Array<{
         expected: PluginManifest;
         installed: PluginManifest | null;
+        installation: Installation | null;
         optionKeys: string[];
         optionsSchema: Record<string, unknown> | null;
         documentation: string | null;
@@ -20,5 +24,7 @@ export interface Inspection {
     diagnostics: Diagnostic[];
 }
 export declare class ProjectInspector {
-    inspect(directory: string): Promise<Inspection>;
+    inspect(directory: string, settings?: {
+        runChecks?: boolean;
+    }): Promise<Inspection>;
 }