@dokebi/cli 0.1.0 → 0.2.0

package/dist/project-inspector.js

@@ -1,27 +1,32 @@
-// [AI:수정] CLI 진단·스키마·회귀 검증의 포맷과 import 순서를 맞춘다.
 import { readdir, readFile, realpath } from 'node:fs/promises';
-// [AI:수정] 설치 버전과 package.json의 요청 범위가 다른 경우도 진단한다.
 import satisfies from 'semver/functions/satisfies.js';
 import valid from 'semver/functions/valid.js';
+import { CONFIG_FILE, LEGACY_CONFIG_FILE, parseProjectConfig } from './configuration.js';
 import { CliError } from './errors.js';
 import { exists, fingerprint, hash, json, parseObject, securePath } from './filesystem.js';
+import { legacyLayout } from './layout.js';
 import { orderPlugins, readManifest } from './manifest.js';
 import { dependencyMap, validateProjectPackage } from './npm-client.js';
-// [AI:수정] 설치 버전의 옵션 스키마와 문서 위치를 공개하고 옵션 오류를 진단한다.
-import { checkPluginOptions } from './plugin-options.js';
-import { readConfig, readState } from './project-state.js';
-// Reads metadata only. Never imports plugin entry points or creates locks.
+import { checkPlugin } from './plugin-lifecycle.js';
+import { PluginOptionsValidator } from './plugin-options.js';
+import { readState } from './project-state.js';
+import { readRequiredPlugins } from './required-plugins.js';
+import { installedPath } from './workspace.js';
+// Reads metadata only and never creates locks. With runChecks (doctor), each plugin's
+// installation module check runs in the permission-restricted child process.
 export class ProjectInspector {
-    async inspect(directory) {
+    async inspect(directory, settings = {}) {
         const root = await realpath(directory);
         const result = {
             root,
             healthy: false,
             coreVersion: null,
+            requiredPlugins: [],
             plugins: [],
             diagnostics: [],
         };
         const originals = new Map();
+        const optionsValidator = new PluginOptionsValidator();
         const issue = (code, path, plugin = null, severity = 'error') => {
             result.diagnostics.push({ code, path, plugin, severity });
         };
@@ -35,17 +40,35 @@ export class ProjectInspector {
                     : error instanceof Error && 'code' in error && typeof error.code === 'string'
                         ? error.code
                         : 'READ_FAILED';
-                issue(code, path, plugin);
+                result.diagnostics.push({
+                    code,
+                    path,
+                    plugin,
+                    severity: 'error',
+                    ...(error instanceof CliError && error.details !== undefined
+                        ? { details: error.details }
+                        : {}),
+                });
                 return null;
             }
         };
         const read = async (path) => {
-            const text = await readFile(await securePath(root, path), 'utf8');
+            // node_modules paths resolve like Node in a workspace member (D-0035).
+            const text = await readFile(await installedPath(root, path), 'utf8');
             originals.set(path, hash(text));
             return text;
         };
         const state = await check('.dokebi/state.json', async () => readState(parseObject(await read('.dokebi/state.json'), 'state')));
-        const config = await check('dokebi.json', async () => readConfig(parseObject(await read('dokebi.json'), 'config')));
+        const config = await check(CONFIG_FILE, async () => {
+            if (await exists(await securePath(root, LEGACY_CONFIG_FILE)))
+                throw new CliError((await exists(await securePath(root, CONFIG_FILE)))
+                    ? 'CONFIG_CONFLICT'
+                    : 'MIGRATION_REQUIRED', 'Explicit YAML migration is required');
+            return parseProjectConfig(await read(CONFIG_FILE));
+        });
+        result.requiredPlugins =
+            (await check('node_modules/@dokebi/core/package.json', () => readRequiredPlugins(root))) ??
+                [];
         const pkg = await check('package.json', async () => {
             const value = parseObject(await read('package.json'), 'package');
             validateProjectPackage(value);
@@ -90,18 +113,17 @@ export class ProjectInspector {
                     issue('MISSING_PACKAGE_DEPENDENCY', 'package.json', plugin.id);
                 if (installed)
                     matches(installed.packageName, installed.version, plugin.id);
-                // [AI:수정] 추가한 버전·옵션 경계 검사를 저장소 포맷에 맞춘다.
                 const options = config && Object.hasOwn(config.options, plugin.id)
                     ? config.options[plugin.id]
                     : undefined;
                 const checked = installed
-                    ? await check(path, async () => checkPluginOptions(root, installed, options ?? {}), plugin.id)
+                    ? await check(path, async () => optionsValidator.check(root, installed, options ?? {}), plugin.id)
                     : null;
                 if (checked?.errors.length)
                     result.diagnostics.push({
                         code: 'INVALID_PLUGIN_OPTIONS',
                         severity: 'error',
-                        path: 'dokebi.json',
+                        path: CONFIG_FILE,
                         plugin: plugin.id,
                         details: checked.errors,
                     });
@@ -112,9 +134,56 @@ export class ProjectInspector {
                     if (guide !== null)
                         documentation = candidate;
                 }
+                const installation = state.installations[plugin.id] ?? null;
+                if (installation?.entry) {
+                    const entry = installation.entry;
+                    const present = await check(entry, async () => exists(await securePath(root, entry)));
+                    if (present === false)
+                        issue('ENTRY_MISSING', entry, plugin.id);
+                    // Installed before the D-0031 layout: it keeps working where it is.
+                    if (legacyLayout(entry, plugin.id))
+                        issue('LEGACY_LAYOUT', entry, plugin.id, 'warning');
+                }
+                if (settings.runChecks && installed && config && pkg) {
+                    const verdict = await check(path, () => checkPlugin({
+                        base: root,
+                        plugin: installed,
+                        options: config.options,
+                        plugins: state.plugins,
+                        projectPackages: Object.keys(pkg),
+                        ...(installation ? { installation } : {}),
+                    }), plugin.id);
+                    if (verdict) {
+                        const ids = new Set(state.plugins.map((item) => item.id));
+                        const missing = verdict.requires.filter((id) => !ids.has(id));
+                        if (missing.length)
+                            result.diagnostics.push({
+                                code: 'MISSING_REQUIRED_PLUGIN',
+                                severity: 'error',
+                                path: CONFIG_FILE,
+                                plugin: plugin.id,
+                                details: { requires: missing },
+                            });
+                        const recorded = [...(installation?.requires ?? [])].sort();
+                        if (json(recorded) !== json([...verdict.requires].sort()))
+                            issue('STALE_REQUIREMENTS', '.dokebi/state.json', plugin.id, 'warning');
+                        for (const item of verdict.diagnostics)
+                            result.diagnostics.push({
+                                code: 'PLUGIN_CHECK',
+                                severity: item.severity,
+                                path: CONFIG_FILE,
+                                plugin: plugin.id,
+                                details: {
+                                    code: item.code,
+                                    ...(item.optionPath ? { optionPath: item.optionPath } : {}),
+                                },
+                            });
+                    }
+                }
                 result.plugins.push({
                     expected: plugin,
                     installed,
+                    installation,
                     optionsSchema: checked?.schema ?? null,
                     documentation,
                     optionKeys: options && typeof options === 'object' && !Array.isArray(options)
@@ -123,20 +192,16 @@ export class ProjectInspector {
                 });
             }
             if (core)
-                await check('.dokebi/state.json', async () => orderPlugins(state.plugins, core));
+                await check('.dokebi/state.json', async () => orderPlugins(state.plugins, core, result.requiredPlugins));
             for (const [path, owned] of Object.entries(state.files)) {
                 const actual = await check(path, async () => fingerprint(await securePath(root, path)));
                 if (actual !== owned.hash)
                     issue('MODIFIED_TEMPLATE', path, null, 'warning');
             }
-            for (const id of Object.keys(config?.options ?? {})) {
-                if (!state.plugins.some((plugin) => plugin.id === id))
-                    issue('ORPHAN_OPTIONS', 'dokebi.json', id, 'warning');
-            }
         }
         for (const [path, expected] of originals) {
             await check(path, async () => {
-                if (hash(await readFile(await securePath(root, path))) !== expected)
+                if (hash(await readFile(await installedPath(root, path))) !== expected)
                     throw new CliError('CONCURRENT_CHANGE', 'Metadata changed during inspection');
                 return true;
             });

package/dist/project-state.d.ts

@@ -3,16 +3,31 @@ export interface OwnedFile {
     hash: string;
     owners: string[];
 }
+/** Per-plugin results of the install lifecycle that are not part of the package manifest. */
+export interface Installation {
+    entry?: string;
+    requires: string[];
+    directories: string[];
+}
 export interface ProjectState {
-    schemaVersion: 1;
+    schemaVersion: 2;
     plugins: PluginManifest[];
+    installations: Record<string, Installation>;
     files: Record<string, OwnedFile>;
     generatedHash: string;
+    /** Apps of @dokebi/app in registration order (src/apps/<name>/app.ts), D-0030. */
+    apps?: string[];
+    /** Modules of @dokebi/module in registration order (src/shared/modules/<name>), D-0032. */
+    modules?: string[];
 }
+/** App and template names: lower-case letters, digits and hyphens, starting with a letter. */
+export declare const APP_NAME: RegExp;
 export interface ProjectConfig {
     schemaVersion: 1;
     options: Record<string, unknown>;
 }
 export declare function emptyState(generatedHash: string): ProjectState;
+export declare function defaultInstallation(plugin: PluginManifest): Installation;
+/** Reads schema 1 (pre contract v2) and schema 2 state; callers always write schema 2. */
 export declare function readState(value: unknown): ProjectState;
 export declare function readConfig(value: unknown): ProjectConfig;

package/dist/project-state.js

@@ -1,24 +1,40 @@
-// [AI:생성] 설치 중 플러그인 코드를 실행하지 않고 실제 인스턴스로 의존 플러그인을 연결한다.
 import { CliError } from './errors.js';
 import { object, templateTarget } from './filesystem.js';
-import { readManifest } from './manifest.js';
+import { ID, readStoredManifest } from './manifest.js';
+/** App and template names: lower-case letters, digits and hyphens, starting with a letter. */
+export const APP_NAME = /^[a-z][a-z0-9-]{0,31}$/;
 export function emptyState(generatedHash) {
-    return { schemaVersion: 1, plugins: [], files: Object.create(null), generatedHash };
+    return {
+        schemaVersion: 2,
+        plugins: [],
+        installations: Object.create(null),
+        files: Object.create(null),
+        generatedHash,
+    };
 }
+export function defaultInstallation(plugin) {
+    return { requires: [], directories: [...(plugin.directories ?? [])] };
+}
+function stringList(value, check) {
+    if (!Array.isArray(value))
+        throw new CliError('INVALID_STATE', 'Invalid installation list');
+    const result = [];
+    for (const item of value) {
+        if (typeof item !== 'string' || result.includes(item))
+            throw new CliError('INVALID_STATE', 'Invalid installation list');
+        check(item);
+        result.push(item);
+    }
+    return result;
+}
+/** Reads schema 1 (pre contract v2) and schema 2 state; callers always write schema 2. */
 export function readState(value) {
     const input = object(value, 'state');
-    if (input.schemaVersion !== 1 ||
+    if ((input.schemaVersion !== 1 && input.schemaVersion !== 2) ||
         !Array.isArray(input.plugins) ||
         typeof input.generatedHash !== 'string')
         throw new CliError('INVALID_STATE', 'Unsupported project state');
-    const plugins = input.plugins.map((entry) => {
-        const plugin = object(entry, 'plugin');
-        return readManifest({
-            name: plugin.packageName,
-            version: plugin.version,
-            dokebi: { ...plugin, schemaVersion: 1 },
-        });
-    });
+    const plugins = input.plugins.map((entry) => readStoredManifest(entry));
     if (new Set(plugins.map((plugin) => plugin.id)).size !== plugins.length ||
         new Set(plugins.map((plugin) => plugin.packageName)).size !== plugins.length)
         throw new CliError('INVALID_STATE', 'Duplicate installed plugin');
@@ -35,7 +51,65 @@ export function readState(value) {
             throw new CliError('INVALID_STATE', 'Invalid file ownership');
         files[path] = { hash: file.hash, owners: file.owners };
     }
-    return { schemaVersion: 1, plugins, files, generatedHash: input.generatedHash };
+    const installations = Object.create(null);
+    if (input.schemaVersion === 1) {
+        for (const plugin of plugins)
+            installations[plugin.id] = defaultInstallation(plugin);
+    }
+    else {
+        const stored = object(input.installations, 'installations');
+        const ids = new Set(plugins.map((plugin) => plugin.id));
+        if (Object.keys(stored).length !== ids.size || Object.keys(stored).some((id) => !ids.has(id)))
+            throw new CliError('INVALID_STATE', 'Installations must match installed plugins');
+        for (const [id, raw] of Object.entries(stored)) {
+            const item = object(raw, 'installation');
+            if (Object.keys(item).some((key) => !['entry', 'requires', 'directories'].includes(key)))
+                throw new CliError('INVALID_STATE', 'Unknown installation field');
+            const installation = {
+                requires: stringList(item.requires, (name) => {
+                    if (!ID.test(name) || name === id)
+                        throw new CliError('INVALID_STATE', 'Invalid plugin requirement');
+                }),
+                directories: stringList(item.directories, templateTarget),
+            };
+            if (item.entry !== undefined) {
+                if (typeof item.entry !== 'string')
+                    throw new CliError('INVALID_STATE', 'Invalid entry');
+                templateTarget(item.entry);
+                if (!files[item.entry]?.owners.includes(id))
+                    throw new CliError('INVALID_STATE', 'Entry file must be owned by its plugin');
+                installation.entry = item.entry;
+            }
+            installations[id] = installation;
+        }
+    }
+    let apps;
+    if (input.apps !== undefined) {
+        apps = stringList(input.apps, (name) => {
+            if (!APP_NAME.test(name))
+                throw new CliError('INVALID_STATE', 'Invalid app name');
+        });
+        if (apps.length && !plugins.some((plugin) => plugin.id === 'dokebi-app'))
+            throw new CliError('INVALID_STATE', 'Apps need the dokebi-app plugin');
+    }
+    let modules;
+    if (input.modules !== undefined) {
+        modules = stringList(input.modules, (name) => {
+            if (!APP_NAME.test(name))
+                throw new CliError('INVALID_STATE', 'Invalid module name');
+        });
+        if (modules.length && !plugins.some((plugin) => plugin.id === 'dokebi-module'))
+            throw new CliError('INVALID_STATE', 'Modules need the dokebi-module plugin');
+    }
+    return {
+        schemaVersion: 2,
+        plugins,
+        installations,
+        files,
+        generatedHash: input.generatedHash,
+        ...(apps?.length ? { apps } : {}),
+        ...(modules?.length ? { modules } : {}),
+    };
 }
 export function readConfig(value) {
     const config = object(value, 'config');

package/dist/project.d.ts

@@ -1,16 +1,95 @@
+import { type SetOption, type Warning } from './config-edit.js';
 import { NpmClient } from './npm-client.js';
+export interface ConfigRequirement {
+    plugin: string;
+    errors: Array<{
+        instancePath: string;
+        keyword: string;
+    }>;
+    errorCount: number;
+}
+export interface PreservedDetail {
+    path: string;
+    reason: 'MODIFIED' | 'DELETED' | 'SHARED';
+    update?: string;
+}
 export interface OperationResult {
     changed: string[];
     preserved: string[];
+    preservedDetails?: PreservedDetail[];
+    configRequired?: ConfigRequirement[];
+    /** Required plugins installed together with the requested one (manifest `package`). */
+    autoInstalled?: Array<{
+        id: string;
+        packageName: string;
+        version: string;
+    }>;
+    warnings?: Array<Warning & {
+        plugin?: string;
+    }>;
+    /** Commands to run after this one (for example the Vite build of a new Inertia app). */
+    nextSteps?: string[];
+    from?: string;
+    to?: string;
+    /** npm workspace root where `npm install` ran (or, in a dry run, would run) (D-0035). */
+    workspaceInstall?: string;
 }
 export declare class Project {
+    #private;
     private readonly npm;
     constructor(npm?: NpmClient);
     init(target: string, core?: string): Promise<OperationResult>;
-    add(root: string, spec: string, dryRun?: boolean): Promise<OperationResult>;
+    migrate(root: string, dryRun?: boolean): Promise<OperationResult>;
+    add(root: string, spec: string, dryRun?: boolean, sets?: readonly SetOption[]): Promise<OperationResult>;
     remove(root: string, id: string, dryRun?: boolean): Promise<OperationResult>;
+    upgrade(root: string, id: string, to?: string, dryRun?: boolean): Promise<OperationResult>;
     private coreVersion;
-    private change;
-    private addFiles;
+    /**
+     * `dokebi app add <name>`: copies the app skeleton of @dokebi/app to src/apps/<name>, maps the
+     * given domains to it in dokebi.yaml and registers it in the generated code (D-0030 §7).
+     */
+    appAdd(root: string, name: string, options?: {
+        domains?: readonly string[];
+        template?: string;
+        dryRun?: boolean;
+        inertia?: boolean;
+    }): Promise<OperationResult>;
+    /** `dokebi app link <app> <domain> [--template t]`: maps one more domain to an existing app. */
+    appLink(root: string, name: string, domain: string, options?: {
+        template?: string;
+        dryRun?: boolean;
+    }): Promise<OperationResult>;
+    /** `dokebi app unlink <domain>`: removes one domain mapping from dokebi.yaml and the sample. */
+    appUnlink(root: string, domain: string, dryRun?: boolean): Promise<OperationResult>;
+    /** `dokebi app remove <name>`: unregisters the app; its folder is user code and stays. */
+    appRemove(root: string, name: string, dryRun?: boolean): Promise<OperationResult>;
+    /** `dokebi app list`: apps with the domains and templates that show them. */
+    appList(root: string): Promise<{
+        apps: {
+            name: string;
+            domains: {
+                domain: string;
+                template: string;
+            }[];
+        }[];
+    }>;
+    /**
+     * `dokebi module add <name>` (D-0032): copies the module skeleton of @dokebi/module to
+     * src/shared/modules/<name> and registers it in the generated code. `views: false` copies the
+     * skeleton without views (routes answer JSON).
+     */
+    moduleAdd(root: string, name: string, options?: {
+        views?: boolean;
+        dryRun?: boolean;
+    }): Promise<OperationResult>;
+    /** `dokebi module remove <name>`: unregisters the module; its folder is user code and stays. */
+    moduleRemove(root: string, name: string, dryRun?: boolean): Promise<OperationResult>;
+    /** `dokebi module list`: the registered modules in registration order. */
+    moduleList(root: string): Promise<{
+        modules: {
+            name: string;
+            path: string;
+        }[];
+    }>;
     private writeConfiguration;
 }