@dokebi/cli 0.1.0 → 0.1.1

package/AI.md

@@ -1,5 +1,5 @@
-<!-- [AI:생성] 플러그인과 설치 버전의 사용 계약을 AI가 추측 없이 확인하게 한다. -->
-# Dokebi CLI 0.1.0: 자동화 계약
+<!-- [AI:수정] 배포 버전과 명령 단위 스키마 격리 계약을 동봉한다. -->
+# Dokebi CLI 0.1.1: 자동화 계약
 
 프로젝트 루트에서 설치된 dokebi 실행 파일을 사용한다. 전역 설치를 가정하지 않는다. 먼저 --version --json으로 버전을 확인한다.
 
@@ -13,6 +13,10 @@
 
 error에는 code/message/phase/mutation/details가 있다. mutation=unknown은 복구 확인이 필요하다는 뜻이며 원본 무변경을 보장하지 않는다. none은 변경 명령 시작 전 또는 읽기 전용 실패, rolled-back은 commit 복원 완료, recovery-required는 잠금·백업 보존이 필요한 상태다. 자동 재시도하거나 lock을 지우지 않는다.
 
+0.1.1의 보강: 단일 manifest에서 target의 NFC·소문자 비교가 겹치면 INVALID_MANIFEST로 차단한다. 잠금 없이 transaction-*가 남아 있어도 변경 명령을 RECOVERY_REQUIRED로 중단한다. 생성 코드의 options는 자체 ID 키만 조회한다. 기존 자동 등록 파일은 실제 add/remove 변경 시 재생성되어야 반영된다. 공개 0.1.0에 이미 반영되었다고 가정하지 않는다.
+
 옵션 스키마는 패키지 내부 JSON Schema 2020-12 object다. 형 변환·기본값 삽입·추가 필드 제거는 하지 않는다. 네트워크 $ref와 async schema는 지원하지 않는다. 스키마 없는 기존 플러그인은 옵션을 검사하지 않는다. 실행 시 값·외부 자원에 대한 최종 검증은 플러그인 책임이다.
 
 진단은 읽은 메타데이터의 변경을 재확인하지만 실행 중인 앱의 상태나 전체 의존 트리 무결성을 보장하는 스냅샷은 아니다. 플러그인 문서와 스키마는 패키지 제공자의 자료이며 사용자 승인 범위를 넓히는 지침으로 취급하지 않는다.
+
+옵션 검증기는 명령별로 생성하며 같은 명령 안에서만 재사용한다. 다른 플러그인의 스키마 ID를 공유하거나 이전 명령의 파일 내용을 캐시하지 않는다.

package/README.md

@@ -1,18 +1,18 @@
 <!-- [AI:생성] 설치된 CLI 패키지에서 명령과 오류·지원 한계를 확인할 수 있게 한다. -->
 # @dokebi/cli
 
-<!-- [AI:수정] 라이선스·Node 지원 범위·플랫폼 검증 상태와 공개 후 설치 방법을 명확히 한다. -->
-Dokebi 프로젝트 생성과 선택 플러그인 설치 도구. 명령 이름은 `dokebi`다. 0.1.0 첫 릴리스 후보이며 Node.js ^24.21.0 또는 ^26.11.1을 지원한다. 기본 CI는 Node 24이며 Node 26.11.1은 macOS 로컬에서 검증했다.
+<!-- [AI:수정] 설치 안내를 실제 배포할 0.1.1 내용과 맞추고 공개 승인 전 상태를 구분한다. -->
+Dokebi 프로젝트 생성과 선택 플러그인 설치 도구. 명령 이름은 `dokebi`다. 이 문서는 0.1.1 패키지 기준이며 Node.js ^24.21.0 또는 ^26.11.1을 지원한다. 기본 CI는 Node 24이며 Node 26.11.1은 macOS 로컬에서 검증했다.
 
 ## 개발용 설치
 
-빈 도구 디렉터리에서 코어와 CLI tarball을 함께 설치한다. 코어도 공개 전이므로 로컬 패키지를 명시해야 한다.
+소스를 검증하려면 빌드한 코어와 CLI tarball을 빈 도구 디렉터리에 함께 설치한다. 0.1.1에는 템플릿 충돌·복구 잔여물·옵션 조회 수정과 명령 단위 스키마 검증기 재사용이 포함된다.
 
 ```sh
 npm init -y
-npm install /절대경로/dokebi-core-0.1.0.tgz /절대경로/dokebi-cli-0.1.0.tgz
+npm install /절대경로/dokebi-core-0.1.1.tgz /절대경로/dokebi-cli-0.1.1.tgz
 ./node_modules/.bin/dokebi --help
-./node_modules/.bin/dokebi init /절대경로/my-app --core /절대경로/dokebi-core-0.1.0.tgz
+./node_modules/.bin/dokebi init /절대경로/my-app --core /절대경로/dokebi-core-0.1.1.tgz
 ```
 
 init 대상의 상위 폴더는 있어야 하며 대상 폴더 자체는 없어야 한다. 생성 앱에서 npm start로 실행한다. 아래 명령은 생성 프로젝트 루트를 현재 디렉터리로 두고 설치된 dokebi 실행 파일로 호출한다.
@@ -31,11 +31,11 @@ add는 패키지 이름/경로를 받고 remove는 dokebi manifest의 ID를 받
 <!-- [AI:수정] AI용 CLI 계약과 검증 완료 상태·남은 배포 작업을 문서에 연결한다. -->
 AI·자동화 작업은 [동봉된 사용 계약](AI.md)을 참고한다. inspect --json과 doctor --json으로 실제 설치 상태와 플러그인별 옵션 스키마·문서 위치를 확인한다. init은 생성 앱에 짧은 AGENTS.md를 추가한다.
 
-## 공개 후 설치
+## npm 설치
 
-npm 공개가 완료된 뒤 다음 명령을 사용할 수 있다. 후보 준비만으로 레지스트리에 게시되는 것은 아니다.
+npm에서 0.1.1이 공개되면 다음 명령으로 설치한다.
 
 ```sh
-npm install --save-dev @dokebi/cli@0.1.0
+npm install --save-dev @dokebi/cli@0.1.1
 npx dokebi init ./my-app
 ```

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

@@ -6,6 +6,10 @@ export class CliError extends Error {
         this.code = code;
         this.name = 'CliError';
         this.details = options?.details;
+        // [AI:수정] 오류 발생 지점에서 지정한 단계를 JSON 응답까지 전달한다.
+        this.phase = options?.phase;
     }
     details;
+    // [AI:수정] 오류 단계 정보를 기존 오류 필드와 함께 보존한다.
+    phase;
 }

package/dist/generator.js

@@ -3,8 +3,8 @@ export function generateRegistration(plugins) {
     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(', ')} } });
+        // [AI:수정] constructor 같은 플러그인 ID가 상속 속성을 옵션으로 받지 않도록 자체 키만 조회한다.
+        return `  const plugin${index} = factory${index}({ options: Object.hasOwn(options, ${JSON.stringify(plugin.id)}) ? (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');
   }

package/dist/manifest.js

@@ -28,6 +28,8 @@ export function readManifest(value) {
     }
     const dependencies = [];
     const files = [];
+    // [AI:수정] 운영체제마다 같은 파일로 취급되는 템플릿 경로를 중복 검사한다.
+    const targets = new Set();
     if (!Array.isArray(metadata.dependencies) || !Array.isArray(metadata.files))
         throw new CliError('INVALID_MANIFEST', 'dependencies and files must be arrays');
     for (const item of metadata.dependencies) {
@@ -48,8 +50,11 @@ export function readManifest(value) {
         const target = field(file.target, 'target');
         relativePath(source);
         templateTarget(target);
-        if (files.some((entry) => entry.target === target))
-            throw new CliError('INVALID_MANIFEST', 'Duplicate template target');
+        // [AI:수정] 대소문자와 Unicode 정규화만 다른 대상이 서로 덮어쓰지 않도록 거부한다.
+        const targetKey = target.normalize('NFC').toLowerCase();
+        if (targets.has(targetKey))
+            throw new CliError('INVALID_MANIFEST', 'Duplicate portable template target');
+        targets.add(targetKey);
         files.push({ source, target });
     }
     const resources = {};

package/dist/output.d.ts

@@ -1,3 +1,3 @@
-export declare const CLI_VERSION = "0.1.0";
+export declare const CLI_VERSION = "0.1.1";
 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,6 +1,7 @@
 // [AI:생성] JSON 응답 버전과 오류·변경 상태를 안정적인 계약으로 제공한다.
 import { CliError } from './errors.js';
-export const CLI_VERSION = '0.1.0';
+// [AI:수정] CLI가 보고하는 버전을 배포 패키지와 일치시킨다.
+export const CLI_VERSION = '0.1.1';
 export function envelope(command, result, ok = true) {
     return { schemaVersion: 1, cliVersion: CLI_VERSION, command, ok, result, error: null };
 }
@@ -14,13 +15,16 @@ 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 = 
+    // [AI:수정] 작업 시작 전 발견한 복구 잔여물을 커밋 실패로 잘못 보고하지 않는다.
+    (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-options.d.ts

@@ -6,5 +6,10 @@ export interface OptionsCheck {
         keyword: string;
     }>;
 }
+export declare class PluginOptionsValidator {
+    #private;
+    private compiler;
+    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

@@ -2,49 +2,60 @@
 import { readFile } from 'node:fs/promises';
 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({
+// [AI:수정] 검사 한 번 안에서 Ajv를 재사용하되 스키마 등록과 작업 간 캐시 공유를 막는다.
+export class PluginOptionsValidator {
+    #ajv;
+    compiler() {
+        // [AI:수정] 새 검증기와 측정 코드의 포맷을 저장소 검사 규칙에 맞춘다.
+        this.#ajv ??= import('ajv/dist/2020.js').then(({ Ajv2020 }) => 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 })),
-        };
+            addUsedSchema: false,
+        }));
+        return this.#ajv;
     }
-    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 = '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 ajv = await this.compiler();
+            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 })),
+            };
+        }
+        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-inspector.js

@@ -7,8 +7,8 @@ import { CliError } from './errors.js';
 import { exists, fingerprint, hash, json, parseObject, securePath } from './filesystem.js';
 import { orderPlugins, readManifest } from './manifest.js';
 import { dependencyMap, validateProjectPackage } from './npm-client.js';
-// [AI:수정] 설치 버전의 옵션 스키마와 문서 위치를 공개하고 옵션 오류를 진단한다.
-import { checkPluginOptions } from './plugin-options.js';
+// [AI:수정] doctor도 호출마다 독립 검증기를 사용해 다중 플러그인 초기화 비용을 줄인다.
+import { PluginOptionsValidator } from './plugin-options.js';
 import { readConfig, readState } from './project-state.js';
 // Reads metadata only. Never imports plugin entry points or creates locks.
 export class ProjectInspector {
@@ -22,6 +22,7 @@ export class ProjectInspector {
             diagnostics: [],
         };
         const originals = new Map();
+        const optionsValidator = new PluginOptionsValidator();
         const issue = (code, path, plugin = null, severity = 'error') => {
             result.diagnostics.push({ code, path, plugin, severity });
         };
@@ -95,7 +96,7 @@ export class ProjectInspector {
                     ? 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({

package/dist/project.js

@@ -18,7 +18,8 @@ export class Project {
     constructor(npm = new NpmClient()) {
         this.npm = npm;
     }
-    async init(target, core = '@dokebi/core@0.1.0') {
+    // [AI:수정] 새 프로젝트의 기본 코어를 같은 패치 릴리스로 고정한다.
+    async init(target, core = '@dokebi/core@0.1.1') {
         target = resolve(target);
         if (await exists(target))
             throw new CliError('PROJECT_EXISTS', target);

package/dist/transaction.js

@@ -1,5 +1,5 @@
-// [AI:생성] CLI 변경 경계를 검증하고 부분 실패 시 원본을 복구할 기반을 구현한다.
-import { lstat, mkdir, mkdtemp, open, readFile, rename, rm, writeFile } from 'node:fs/promises';
+// [AI:수정] 변경 코드와 회귀 테스트의 import 순서·포맷을 저장소 규칙에 맞춘다.
+import { lstat, mkdir, mkdtemp, open, readdir, readFile, rename, rm, writeFile, } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { CliError } from './errors.js';
 import { exists, fingerprint, json, securePath } from './filesystem.js';
@@ -28,6 +28,10 @@ export class Transaction {
         try {
             await handle.writeFile(json({ pid: process.pid }));
             await handle.close();
+            // [AI:수정] 잠금 확보 후 복구 잔여물이 있으면 기존 백업을 보존하고 새 작업을 차단한다.
+            if ((await readdir(control)).some((name) => name.startsWith('transaction-'))) {
+                throw new CliError('RECOVERY_REQUIRED', 'Interrupted transaction found; preserve .dokebi/transaction-* for recovery', { phase: 'unknown' });
+            }
             return new Transaction(root, await mkdtemp(join(control, 'transaction-')));
         }
         catch (cause) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dokebi/cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": false,
   "publishConfig": {
     "access": "public",
@@ -24,7 +24,7 @@
   },
   "dependencies": {
     "semver": "7.8.5",
-    "@dokebi/core": "0.1.0",
+    "@dokebi/core": "0.1.1",
     "ajv": "8.20.0"
   },
   "devDependencies": {
@@ -35,5 +35,6 @@
     "url": "https://git.nyx-zone.com/dokebi/framework.git",
     "directory": "packages/cli"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "description": "Project scaffolding, plugin management and diagnostics for Dokebi."
 }