@dokebi/cli 0.0.0-stage → 0.1.0

package/AI.md

@@ -0,0 +1,18 @@
+<!-- [AI:생성] 플러그인과 설치 버전의 사용 계약을 AI가 추측 없이 확인하게 한다. -->
+# Dokebi CLI 0.1.0: 자동화 계약
+
+프로젝트 루트에서 설치된 dokebi 실행 파일을 사용한다. 전역 설치를 가정하지 않는다. 먼저 --version --json으로 버전을 확인한다.
+
+1. inspect --json: 기록된 expected와 실제 installed manifest, coreVersion, optionsSchema, documentation, diagnostics를 조회한다. 조회 성공이어도 result.healthy=false일 수 있다.
+2. doctor --json: 같은 검사에서 error 진단이 있으면 종료 코드 1이다. 파일·잠금을 생성하거나 npm·플러그인 코드를 실행하지 않는다. 네트워크 접근이나 자동 복구를 하지 않는다.
+3. 플러그인별 documentation 경로와 optionsSchema를 읽는다. 설정 값은 출력하지 않으며 optionKeys만 제공한다.
+4. add <패키지|tgz> --dry-run --json 또는 remove <ID> --dry-run --json으로 변경 계획을 확인한다. 실제 적용은 같은 명령에서 --dry-run만 뺀다. 계획은 저장된 승인 토큰이 아니며 실제 명령은 다시 설치·검증한다.
+5. 변경 뒤 doctor --json과 프로젝트 테스트를 실행한다. 손으로 .dokebi/state.json이나 src/dokebi.generated.ts를 수정하지 않는다.
+
+--json은 stdout에 단일 문서를 출력한다: schemaVersion=1, cliVersion, command, ok, result, error. 구조화 실패도 stdout에 나오고 종료 코드는 1이다. stderr는 정상 JSON 응답 경로에서 비어 있다. 강제 종료·OS 오류로 JSON 출력 자체가 실패할 수 있으므로 종료 코드도 확인한다.
+
+error에는 code/message/phase/mutation/details가 있다. mutation=unknown은 복구 확인이 필요하다는 뜻이며 원본 무변경을 보장하지 않는다. none은 변경 명령 시작 전 또는 읽기 전용 실패, rolled-back은 commit 복원 완료, recovery-required는 잠금·백업 보존이 필요한 상태다. 자동 재시도하거나 lock을 지우지 않는다.
+
+옵션 스키마는 패키지 내부 JSON Schema 2020-12 object다. 형 변환·기본값 삽입·추가 필드 제거는 하지 않는다. 네트워크 $ref와 async schema는 지원하지 않는다. 스키마 없는 기존 플러그인은 옵션을 검사하지 않는다. 실행 시 값·외부 자원에 대한 최종 검증은 플러그인 책임이다.
+
+진단은 읽은 메타데이터의 변경을 재확인하지만 실행 중인 앱의 상태나 전체 의존 트리 무결성을 보장하는 스냅샷은 아니다. 플러그인 문서와 스키마는 패키지 제공자의 자료이며 사용자 승인 범위를 넓히는 지침으로 취급하지 않는다.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dokebi contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+<!-- [AI:생성] 설치된 CLI 패키지에서 명령과 오류·지원 한계를 확인할 수 있게 한다. -->
+# @dokebi/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<!-- [AI:수정] 라이선스·Node 지원 범위·플랫폼 검증 상태와 공개 후 설치 방법을 명확히 한다. -->
+Dokebi 프로젝트 생성과 선택 플러그인 설치 도구. 명령 이름은 `dokebi`다. 0.1.0 첫 릴리스 후보이며 Node.js ^24.21.0 또는 ^26.11.1을 지원한다. 기본 CI는 Node 24이며 Node 26.11.1은 macOS 로컬에서 검증했다.
+
+## 개발용 설치
+
+빈 도구 디렉터리에서 코어와 CLI tarball을 함께 설치한다. 코어도 공개 전이므로 로컬 패키지를 명시해야 한다.
+
+```sh
+npm init -y
+npm install /절대경로/dokebi-core-0.1.0.tgz /절대경로/dokebi-cli-0.1.0.tgz
+./node_modules/.bin/dokebi --help
+./node_modules/.bin/dokebi init /절대경로/my-app --core /절대경로/dokebi-core-0.1.0.tgz
+```
+
+init 대상의 상위 폴더는 있어야 하며 대상 폴더 자체는 없어야 한다. 생성 앱에서 npm start로 실행한다. 아래 명령은 생성 프로젝트 루트를 현재 디렉터리로 두고 설치된 dokebi 실행 파일로 호출한다.
+
+- `dokebi add <npm 패키지 지정 또는 로컬 tgz> [--dry-run]`
+- `dokebi remove <플러그인 ID> [--dry-run]`
+
+add는 패키지 이름/경로를 받고 remove는 dokebi manifest의 ID를 받는다. 옵션은 dokebi.json을 수정한다. 자동 생성한 src/dokebi.generated.ts를 직접 수정하면 후속 변경을 거부한다.
+
+성공한 변경 명령은 stdout에 changed/preserved JSON을 출력한다. 실패는 종료 코드 1과 stderr로 보고한다. dry-run도 다운로드·임시 설치 비용이 들 수 있다. 사용자 수정 파일은 제거 시 보존하고 역의존 플러그인이 있으면 제거를 차단한다.
+
+설치 스크립트는 실행하지 않는다. 앱 실행 시에는 플러그인 코드가 실행되므로 신뢰할 패키지만 사용한다. 업그레이드·기존 임의 앱 가져오기·workspace·git/URL 의존성·강제 종료 자동 복구는 지원하지 않는다. MIT 라이선스다. Node 24는 macOS 및 Linux amd64 CI에서 검증했고 Windows 및 OS별 전역 설치는 미검증이다.
+
+자세한 계약과 예제: [Dokebi 저장소](https://git.nyx-zone.com/dokebi/framework).
+
+<!-- [AI:수정] AI용 CLI 계약과 검증 완료 상태·남은 배포 작업을 문서에 연결한다. -->
+AI·자동화 작업은 [동봉된 사용 계약](AI.md)을 참고한다. inspect --json과 doctor --json으로 실제 설치 상태와 플러그인별 옵션 스키마·문서 위치를 확인한다. init은 생성 앱에 짧은 AGENTS.md를 추가한다.
+
+## 공개 후 설치
+
+npm 공개가 완료된 뒤 다음 명령을 사용할 수 있다. 후보 준비만으로 레지스트리에 게시되는 것은 아니다.
+
+```sh
+npm install --save-dev @dokebi/cli@0.1.0
+npx dokebi init ./my-app
+```

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import { CliError } from './errors.js';
+// [AI:수정] 기존 명령의 출력은 유지하며 --json 및 inspect·doctor 명령을 추가한다.
+import { CLI_VERSION, envelope, failure } from './output.js';
+// [AI:수정] CLI 진단·스키마·회귀 검증의 포맷과 import 순서를 맞춘다.
+import { Project } from './project.js';
+import { ProjectInspector } from './project-inspector.js';
+const HELP = 'dokebi init <directory> [--core <package|local.tgz>] [--json]\ndokebi add <package|local.tgz> [--dry-run] [--json]\ndokebi remove <plugin-id> [--dry-run] [--json]\ndokebi inspect [--json]\ndokebi doctor [--json]\n';
+const raw = process.argv.slice(2);
+const machine = raw.includes('--json');
+const args = raw.filter((arg) => arg !== '--json');
+const command = args.shift() ?? '--help';
+let mutationStarted = false;
+async function main() {
+    if (raw.filter((arg) => arg === '--json').length > 1)
+        throw new CliError('USAGE', HELP);
+    if (command === '--help' || command === '--version') {
+        if (args.length)
+            throw new CliError('USAGE', HELP);
+        const value = command === '--help' ? HELP : CLI_VERSION;
+        process.stdout.write(machine
+            ? JSON.stringify(envelope(command, value)) + '\n'
+            : value + (value.endsWith('\n') ? '' : '\n'));
+        return;
+    }
+    if (command === 'inspect' || command === 'doctor') {
+        if (args.length)
+            throw new CliError('USAGE', HELP);
+        const result = await new ProjectInspector().inspect(process.cwd());
+        const ok = command === 'inspect' || result.healthy;
+        process.stdout.write(JSON.stringify(machine ? envelope(command, result, ok) : result, null, 2) + '\n');
+        if (!ok)
+            process.exitCode = 1;
+        return;
+    }
+    const target = args.shift();
+    if (!target || target.startsWith('-'))
+        throw new CliError('USAGE', HELP);
+    const project = new Project();
+    let result;
+    if (command === 'init') {
+        if (args.length &&
+            (args.length !== 2 || args[0] !== '--core' || !args[1] || args[1].startsWith('-')))
+            throw new CliError('USAGE', HELP);
+        mutationStarted = true;
+        result = await project.init(target, args[1]);
+    }
+    else if (command === 'add' || command === 'remove') {
+        if (args.length && (args.length !== 1 || args[0] !== '--dry-run'))
+            throw new CliError('USAGE', HELP);
+        mutationStarted = true;
+        result = await project[command](process.cwd(), target, args[0] === '--dry-run');
+    }
+    else
+        throw new CliError('USAGE', HELP);
+    process.stdout.write(JSON.stringify(machine ? envelope(command, result) : result, null, 2) + '\n');
+}
+await main().catch((error) => {
+    if (machine)
+        process.stdout.write(JSON.stringify(failure(command, error, mutationStarted)) + '\n');
+    else
+        process.stderr.write((error instanceof CliError ? error.code + ': ' + error.message : String(error)) + '\n');
+    process.exitCode = 1;
+});

package/dist/errors.d.ts

@@ -0,0 +1,8 @@
+export interface CliErrorOptions extends ErrorOptions {
+    details?: unknown;
+}
+export declare class CliError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string, options?: CliErrorOptions);
+    readonly details: unknown;
+}

package/dist/errors.js

@@ -0,0 +1,11 @@
+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;
+    }
+    details;
+}

package/dist/filesystem.d.ts

@@ -0,0 +1,10 @@
+import { hash as hashing } from '@dokebi/core/libraries';
+export declare const hash: typeof hashing.sha256;
+export declare const json: (value: unknown) => string;
+export declare function relativePath(path: string): void;
+export declare function templateTarget(path: string): void;
+export declare function exists(path: string): Promise<boolean>;
+export declare function securePath(root: string, relative: string): Promise<string>;
+export declare function fingerprint(path: string): Promise<string | null>;
+export declare function object(value: unknown, label: string): Record<string, unknown>;
+export declare function parseObject(text: string, label: string): Record<string, unknown>;

package/dist/filesystem.js

@@ -0,0 +1,76 @@
+// [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 { join } from 'node:path';
+import { CliError } from './errors.js';
+export const hash = hashing.sha256;
+export const json = (value) => JSON.stringify(value, null, 2) + '\n';
+export function relativePath(path) {
+    if (!paths.isPortableRelativePath(path))
+        throw new CliError('UNSAFE_PATH', `Invalid relative path: ${path}`);
+}
+export function templateTarget(path) {
+    relativePath(path);
+    if (!path.startsWith('src/') || path === 'src/main.ts' || path === 'src/dokebi.generated.ts') {
+        throw new CliError('UNSAFE_PATH', `Template target is reserved: ${path}`);
+    }
+}
+export async function exists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+export async function securePath(root, relative) {
+    relativePath(relative);
+    let path = root;
+    const parts = relative.split('/');
+    for (let index = 0; index < parts.length; index++) {
+        path = join(path, parts[index] ?? '');
+        try {
+            const stat = await lstat(path);
+            if (stat.isSymbolicLink())
+                throw new CliError('UNSAFE_PATH', `Symlink is not allowed: ${relative}`);
+            if (index < parts.length - 1 && !stat.isDirectory()) {
+                throw new CliError('PATH_CONFLICT', `Parent is not a directory: ${relative}`);
+            }
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    return path;
+}
+export async function fingerprint(path) {
+    if (!(await exists(path)))
+        return null;
+    const stat = await lstat(path);
+    if (stat.isSymbolicLink())
+        throw new CliError('UNSAFE_PATH', 'Symlink is not allowed');
+    if (stat.isDirectory())
+        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));
+}
+export function object(value, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new CliError('INVALID_DATA', `Expected object: ${label}`);
+    return value;
+}
+export function parseObject(text, label) {
+    try {
+        return object(JSON.parse(text), label);
+    }
+    catch (cause) {
+        throw new CliError('INVALID_DATA', `Invalid JSON: ${label}`, { cause });
+    }
+}

package/dist/generator.d.ts

@@ -0,0 +1,3 @@
+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";

package/dist/generator.js

@@ -0,0 +1,38 @@
+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});`;
+    });
+    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' };
+${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')}
+}
+`;
+}
+export const MAIN_SOURCE = `import { Application } from '@dokebi/core';
+import { registerPlugins } from './dokebi.generated.ts';
+
+const app = new Application();
+registerPlugins(app);
+await app.start();
+try {
+  app.logger.log('info', 'Dokebi application started');
+  // Run local work here. Long-running apps own their signal and shutdown policy.
+} finally {
+  await app.stop();
+}
+`;

package/dist/manifest.d.ts

@@ -0,0 +1,21 @@
+export interface Dependency {
+    name: string;
+    version: string;
+}
+export interface Template {
+    source: string;
+    target: string;
+}
+export interface PluginManifest {
+    packageName: string;
+    version: string;
+    id: string;
+    core: string;
+    dependencies: Dependency[];
+    files: Template[];
+    optionsSchema?: string;
+    documentation?: string;
+}
+export declare const PACKAGE_NAME: RegExp;
+export declare function readManifest(value: unknown): PluginManifest;
+export declare function orderPlugins(plugins: PluginManifest[], coreVersion: string): PluginManifest[];

package/dist/manifest.js

@@ -0,0 +1,95 @@
+// [AI:생성] CLI 변경 경계를 검증하고 부분 실패 시 원본을 복구할 기반을 구현한다.
+import satisfies from 'semver/functions/satisfies.js';
+import valid from 'semver/functions/valid.js';
+import validRange from 'semver/ranges/valid.js';
+import { CliError } from './errors.js';
+import { object, relativePath, templateTarget } from './filesystem.js';
+export const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+const ID = /^[a-z0-9][a-z0-9._/-]*$/;
+function field(value, label) {
+    if (typeof value !== 'string' || !value)
+        throw new CliError('INVALID_MANIFEST', label);
+    return value;
+}
+export function readManifest(value) {
+    const pkg = object(value, 'package');
+    const metadata = object(pkg.dokebi, 'dokebi');
+    const packageName = field(pkg.name, 'package.name');
+    const version = field(pkg.version, 'package.version');
+    const id = field(metadata.id, 'dokebi.id');
+    const core = field(metadata.core, 'dokebi.core');
+    if (!PACKAGE_NAME.test(packageName) ||
+        !ID.test(id) ||
+        !valid(version) ||
+        !core.trim() ||
+        !validRange(core) ||
+        metadata.schemaVersion !== 1) {
+        throw new CliError('INVALID_MANIFEST', 'Invalid plugin identity, version or schema');
+    }
+    const dependencies = [];
+    const files = [];
+    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) {
+        const dep = object(item, 'dependency');
+        const name = field(dep.name, 'dependency.name');
+        const range = field(dep.version, 'dependency.version');
+        if (!ID.test(name) ||
+            !range.trim() ||
+            !validRange(range) ||
+            dependencies.some((entry) => entry.name === name)) {
+            throw new CliError('INVALID_MANIFEST', 'Invalid or duplicate dependency');
+        }
+        dependencies.push({ name, version: range });
+    }
+    for (const item of metadata.files) {
+        const file = object(item, 'template');
+        const source = field(file.source, 'source');
+        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');
+        files.push({ source, target });
+    }
+    const resources = {};
+    for (const key of ['optionsSchema', 'documentation']) {
+        if (metadata[key] !== undefined) {
+            const path = field(metadata[key], key);
+            relativePath(path);
+            resources[key] = path;
+        }
+    }
+    return { packageName, version, id, core, dependencies, files, ...resources };
+}
+export function orderPlugins(plugins, coreVersion) {
+    const byId = new Map(plugins.map((plugin) => [plugin.id, plugin]));
+    if (byId.size !== plugins.length)
+        throw new CliError('DUPLICATE_PLUGIN', 'Duplicate plugin ID');
+    const visiting = new Set();
+    const visited = new Set();
+    const ordered = [];
+    function visit(plugin) {
+        if (visited.has(plugin.id))
+            return;
+        if (visiting.has(plugin.id))
+            throw new CliError('DEPENDENCY_CYCLE', plugin.id);
+        if (!satisfies(coreVersion, plugin.core))
+            throw new CliError('INCOMPATIBLE_VERSION', plugin.id);
+        visiting.add(plugin.id);
+        for (const dep of plugin.dependencies) {
+            const provider = byId.get(dep.name);
+            if (!provider)
+                throw new CliError('MISSING_DEPENDENCY', dep.name);
+            if (!satisfies(provider.version, dep.version))
+                throw new CliError('INCOMPATIBLE_VERSION', dep.name);
+            visit(provider);
+        }
+        visiting.delete(plugin.id);
+        visited.add(plugin.id);
+        ordered.push(plugin);
+    }
+    for (const plugin of plugins)
+        visit(plugin);
+    return ordered;
+}

package/dist/npm-client.d.ts

@@ -0,0 +1,6 @@
+export declare function packageSpec(spec: string, cwd: string): string;
+export declare function dependencyMap(pkg: Record<string, unknown>): Record<string, string>;
+export declare function validateProjectPackage(pkg: Record<string, unknown>): void;
+export declare class NpmClient {
+    install(directory: string, spec?: string): Promise<void>;
+}

package/dist/npm-client.js

@@ -0,0 +1,89 @@
+// [AI:생성] 설치 중 플러그인 코드를 실행하지 않고 실제 인스턴스로 의존 플러그인을 연결한다.
+import { spawn } from 'node:child_process';
+import { 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;
+}
+export function dependencyMap(pkg) {
+    const result = Object.create(null);
+    for (const [name, value] of Object.entries(object(pkg.dependencies ?? {}, 'dependencies'))) {
+        if (!PACKAGE_NAME.test(name) || typeof value !== 'string')
+            throw new CliError('INVALID_DATA', 'Invalid package dependency');
+        result[name] = value;
+    }
+    return result;
+}
+export function validateProjectPackage(pkg) {
+    if (pkg.workspaces !== undefined)
+        throw new CliError('UNSUPPORTED_PROJECT', 'Workspace projects are not supported');
+    for (const section of ['dependencies', 'devDependencies', 'optionalDependencies']) {
+        for (const value of Object.values(object(pkg[section] ?? {}, section))) {
+            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))) {
+                throw new CliError('UNSUPPORTED_PROJECT', 'Use registry dependencies or absolute file tarballs');
+            }
+        }
+    }
+}
+export class NpmClient {
+    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] : []),
+            'install',
+            ...(spec ? [spec] : []),
+            '--ignore-scripts',
+            '--save-exact',
+            '--no-audit',
+            '--no-fund',
+            '--workspaces=false',
+            '--package-lock=true',
+        ];
+        await new Promise((resolvePromise, reject) => {
+            const child = spawn(command, args, { cwd: directory, stdio: 'ignore' });
+            let timedOut = false;
+            const timer = setTimeout(() => {
+                timedOut = true;
+                child.kill('SIGKILL');
+            }, 120000);
+            child.on('error', (cause) => {
+                clearTimeout(timer);
+                reject(new CliError('NPM_FAILED', 'Could not execute npm', { cause }));
+            });
+            child.on('close', (code) => {
+                clearTimeout(timer);
+                if (code === 0 && !timedOut)
+                    resolvePromise();
+                else
+                    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.d.ts

@@ -0,0 +1,2 @@
+export declare function normalizePackagePaths(pkg: Record<string, unknown>, root: string): void;
+export declare function normalizeLockPaths(lock: Record<string, unknown>, root: string): void;

package/dist/npm-paths.js

@@ -0,0 +1,34 @@
+// [AI:생성] 사용자 데이터를 재귀 순회하지 않고 npm 경로 필드만 보정한다.
+import { resolve } from 'node:path';
+import { object } from './filesystem.js';
+const DEPENDENCY_FIELDS = [
+    // [AI:수정] 데이터 보존 수정과 회귀 테스트에 저장소 포맷을 적용한다.
+    'dependencies',
+    'devDependencies',
+    'optionalDependencies',
+    'peerDependencies',
+];
+function localReference(value, root) {
+    return typeof value === 'string' && value.startsWith('file:')
+        ? `file:${resolve(root, value.slice(5))}`
+        : value;
+}
+export function normalizePackagePaths(pkg, root) {
+    for (const field of DEPENDENCY_FIELDS) {
+        if (pkg[field] === undefined)
+            continue;
+        const dependencies = object(pkg[field], field);
+        for (const name of Object.keys(dependencies)) {
+            dependencies[name] = localReference(dependencies[name], root);
+        }
+    }
+}
+export function normalizeLockPaths(lock, root) {
+    // npm's packages map holds package records; arbitrary metadata remains opaque.
+    for (const value of Object.values(object(lock.packages, 'lock.packages'))) {
+        const pkg = object(value, 'lock package');
+        normalizePackagePaths(pkg, root);
+        if (Object.hasOwn(pkg, 'resolved'))
+            pkg.resolved = localReference(pkg.resolved, root);
+    }
+}

package/dist/output.d.ts

@@ -0,0 +1,3 @@
+export declare const CLI_VERSION = "0.1.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

@@ -0,0 +1,38 @@
+// [AI:생성] JSON 응답 버전과 오류·변경 상태를 안정적인 계약으로 제공한다.
+import { CliError } from './errors.js';
+export const CLI_VERSION = '0.1.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'
+            ? 'rolled-back'
+            : 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';
+    return {
+        schemaVersion: 1,
+        cliVersion: CLI_VERSION,
+        command,
+        ok: false,
+        result: null,
+        error: {
+            code,
+            message: error instanceof Error ? error.message : String(error),
+            phase,
+            mutation,
+            details: error instanceof CliError ? (error.details ?? null) : null,
+        },
+    };
+}

package/dist/plugin-options.d.ts

@@ -0,0 +1,10 @@
+import type { PluginManifest } from './manifest.js';
+export interface OptionsCheck {
+    schema: Record<string, unknown> | null;
+    errors: Array<{
+        instancePath: string;
+        keyword: string;
+    }>;
+}
+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>;