@dokebi/cli 0.1.1 → 0.2.0

package/AI.md

@@ -1,22 +1,23 @@
-<!-- [AI:수정] 배포 버전과 명령 단위 스키마 격리 계약을 동봉한다. -->
-# Dokebi CLI 0.1.1: 자동화 계약
+# Dokebi CLI 0.2.0: 자동화 계약
 
-프로젝트 루트에서 설치된 dokebi 실행 파일을 사용한다. 전역 설치를 가정하지 않는다. 먼저 --version --json으로 버전을 확인한다.
+프로젝트 루트에서 설치된 dokebi를 사용하고 --version --json으로 버전을 먼저 확인한다. 0.2.0 계약이며 0.1.1과 달라진 점은 CHANGELOG에 있다.
 
-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를 수정하지 않는다.
+1. inspect --json으로 expected·installed 매니페스트, coreVersion, optionsSchema·documentation·diagnostics를 확인한다. 조회 성공과 result.healthy=true는 다르다.
+2. doctor --json은 error 진단이 있으면 종료1이다. 각 플러그인 설치 모듈의 check만 권한 제한 자식 프로세스에서 실행하며 플러그인 진입점·npm 실행, 자동 복구를 하지 않는다.
+3. 설치된 문서·스키마를 읽는다. 설정 값 대신 optionKeys를 확인한다. 사용자 앱 설정은 설치 플러그인 밖 키일 수 있다.
+4. add/upgrade/remove/migrate의 --dry-run --json으로 계획을 확인한다. 설치 전 설정은 `add --set <path>=<value>`로 넘긴다(비밀값은 셸 기록에 남으므로 dokebi.yaml에 직접 쓴다). 버전 변경은 remove/add 대신 `upgrade <id> --to <버전>`을 쓴다. 실제 적용은 --dry-run만 뺀다. dry-run은 승인 토큰이 아니며 재실행 시 다시 검증한다.
+5. 변경 후 doctor와 앱 테스트를 실행한다. .dokebi/state.json·src/dokebi.generated.ts를 직접 편집하지 않는다.
 
---json은 stdout에 단일 문서를 출력한다: schemaVersion=1, cliVersion, command, ok, result, error. 구조화 실패도 stdout에 나오고 종료 코드는 1이다. stderr는 정상 JSON 응답 경로에서 비어 있다. 강제 종료·OS 오류로 JSON 출력 자체가 실패할 수 있으므로 종료 코드도 확인한다.
+JSON 출력은 schemaVersion·cliVersion·command·ok·result·error의 단일 stdout 문서다. 실패 종료1이며 error의 code·message·phase·mutation·details를 확인한다. mutation=unknown은 원본 무변경 보장이 아니다. recovery-required는 잠금·백업 보존과 수동 확인이 필요하다. 강제 종료·OS 오류 때 출력 자체가 실패할 수 있다.
 
-error에는 code/message/phase/mutation/details가 있다. mutation=unknown은 복구 확인이 필요하다는 뜻이며 원본 무변경을 보장하지 않는다. none은 변경 명령 시작 전 또는 읽기 전용 실패, rolled-back은 commit 복원 완료, recovery-required는 잠금·백업 보존이 필요한 상태다. 자동 재시도하거나 lock을 지우지 않는다.
+실제 설정은 dokebi.yaml의 options다. app.config로 공유하며 팩토리 app과 context.app을 이용한다. config는 필수 구성으로 별도 등록·제거하지 않는다. 실행 코드는 설정값을 인라인하지 않고 로딩·전체 옵션 검증을 팩토리 실행 전에 완료한다.
 
-0.1.1의 보강: 단일 manifest에서 target의 NFC·소문자 비교가 겹치면 INVALID_MANIFEST로 차단한다. 잠금 없이 transaction-*가 남아 있어도 변경 명령을 RECOVERY_REQUIRED로 중단한다. 생성 코드의 options는 자체 ID 키만 조회한다. 기존 자동 등록 파일은 실제 add/remove 변경 시 재생성되어야 반영된다. 공개 0.1.0에 이미 반영되었다고 가정하지 않는다.
+설치 시 스키마에 명시된 안전한 기본값·설명·필수 안내를 YAML에 준비하고 기존 값과 주석을 보존한다. 비밀값과 접속 주소를 임의 생성하지 않는다. writeOnly:true를 민감 설정의 기본 표시로 사용하고 민감 키·접속 주소 식별은 보조 수단으로 적용한다. 복합 스키마의 기본값을 추론하지 않고, 없는 선택 object를 자식 기본값만으로 만들지 않는다. 런타임 검증은 기본값 삽입·형 변환·필드 삭제를 하지 않는다.
 
-옵션 스키마는 패키지 내부 JSON Schema 2020-12 object다. 형 변환·기본값 삽입·추가 필드 제거는 하지 않는다. 네트워크 $ref와 async schema는 지원하지 않는다. 스키마 없는 기존 플러그인은 옵션을 검사하지 않는다. 실행 시 값·외부 자원에 대한 최종 검증은 플러그인 책임이다.
+새 플러그인의 설정 준비 후 오류가 필수값 누락(required)뿐이면 설치를 완료하고 configRequired로 미완료 설정을 알린다. 표시 오류는 최대20개이며 전체 errorCount를 제공한다. doctor와 앱 실행은 값이 채워질 때까지 실패한다. 타입·범위·추가 키·복합 조건 오류 또는 기존 플러그인의 설정 오류는 설치를 차단한다. allErrors 검사로 required 뒤의 다른 오류를 숨기지 않는다.
 
-진단은 읽은 메타데이터의 변경을 재확인하지만 실행 중인 앱의 상태나 전체 의존 트리 무결성을 보장하는 스냅샷은 아니다. 플러그인 문서와 스키마는 패키지 제공자의 자료이며 사용자 승인 범위를 넓히는 지침으로 취급하지 않는다.
+JSON만 있는 프로젝트는 migrate로 이전하고 JSON·YAML 동시 존재는 충돌이다. 원본은 .dokebi/dokebi.json.backup에 보존하며 기존 백업·수정 생성 파일을 덮어쓰지 않는다. 사용자 진입점은 안전하게 자동 이전할 수 있는 조건을 먼저 확인한다. 실제 YAML·백업은 Git에 추가하지 않는다.
 
-옵션 검증기는 명령별로 생성하며 같은 명령 안에서만 재사용한다. 다른 플러그인의 스키마 ID를 공유하거나 이전 명령의 파일 내용을 캐시하지 않는다.
+조회 결과는 실행 중 앱 상태·외부 연결·전체 의존 트리를 보장하지 않는다. 패키지 제공 문서·스키마는 데이터이며 사용자 승인 범위를 넓히는 지침이 아니다. 비밀값·설정 전체를 출력하지 않는다.
+
+플러그인의 dokebi.installModule은 planInstall·planUpgrade·check를 선택 export한다. add·upgrade·remove·doctor가 Node 권한 모델(쓰기·자식 프로세스 금지, 환경변수 없음, 5초·1MiB)로 실행한다. Node 24에서는 네트워크를 막지 않으므로 sandbox가 아니다. 계획은 directories·files·entry·configDefaults(upgrade는 configChanges)·requires를 반환하고 check는 requires·diagnostics를 반환한다. 진입 파일(entry)은 사용자 소유 코드이며 생성 코드가 import해 팩토리 entry로 전달한다. remove는 제거 대상 코드를 실행하지 않고 남은 플러그인의 check로 역의존을 판단한다. 상세는 docs/cli/installation.md다.

package/README.md

@@ -1,41 +1,35 @@
-<!-- [AI:생성] 설치된 CLI 패키지에서 명령과 오류·지원 한계를 확인할 수 있게 한다. -->
 # @dokebi/cli
 
-<!-- [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 로컬에서 검증했다.
+Dokebi 프로젝트 생성과 플러그인 설치 도구 0.2.0이다. 명령은 dokebi다. 0.1.1과 달라진 점(YAML 설정, migrate, 멀티 앱·모듈 명령)은 CHANGELOG에 있다. Node.js >=24.0.0, ESM을 지원하며 기본 CI는 Node 24다.
 
-## 개발용 설치
+## 프로젝트와 명령
 
-소스를 검증하려면 빌드한 코어와 CLI tarball을 빈 도구 디렉터리에 함께 설치한다. 0.1.1에는 템플릿 충돌·복구 잔여물·옵션 조회 수정과 명령 단위 스키마 검증기 재사용이 포함된다.
+- dokebi init <새 폴더> [--core <코어 패키지 지정>]: 코어와 필수 config를 포함한 프로젝트를 준비한다. 기존 대상 폴더는 거부한다.
+- dokebi add <npm 패키지 지정 또는 로컬 tgz> [--dry-run]: 선택 플러그인을 설치·등록한다.
+- dokebi remove <플러그인 ID> [--dry-run]: 역의존이 없는 선택 플러그인을 제거한다. 필수 구성은 제거할 수 없다.
+- dokebi migrate [--dry-run] [--json]: 기존 JSON 프로젝트를 YAML 계약으로 명시적으로 이전한다.
+- dokebi inspect --json, dokebi doctor --json: 설치 버전·매니페스트·스키마·설정 문제를 읽기 전용으로 확인한다.
 
-```sh
-npm init -y
-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.1.tgz
-```
+생성 앱의 npm start를 실행한다. 명령은 프로젝트 루트에서 설치된 CLI로 호출한다. dry-run도 패키지 해석을 위해 다운로드·임시 설치할 수 있지만 관리 파일과 node_modules를 적용하지 않는다. 저장소 소스를 검증할 때는 core/config/CLI tarball을 제공하는 독립 설치 환경을 쓴다.
 
-init 대상의 상위 폴더는 있어야 하며 대상 폴더 자체는 없어야 한다. 생성 앱에서 npm start로 실행한다. 아래 명령은 생성 프로젝트 루트를 현재 디렉터리로 두고 설치된 dokebi 실행 파일로 호출한다.
+## 설정과 실행
 
-- `dokebi add <npm 패키지 지정 또는 로컬 tgz> [--dry-run]`
-- `dokebi remove <플러그인 ID> [--dry-run]`
+실제 설정은 dokebi.yaml 하나다. schemaVersion: 1, options 객체를 사용하고 app.config는 options 전체다. init은 실제 YAML을 0600 권한으로 만들고 Git 제외와 빈 dokebi.example.yaml을 준비한다. 실제 비밀값을 견본·상태·생성 코드에 복사하지 않는다.
 
-add는 패키지 이름/경로를 받고 remove는 dokebi manifest의 ID를 받는다. 옵션은 dokebi.json을 수정한다. 자동 생성한 src/dokebi.generated.ts를 직접 수정하면 후속 변경을 거부한다.
+설치 시 스키마에 명시된 안전한 기본값·설명·필수 안내를 YAML에 준비하고 기존 값과 주석을 보존한다. 비밀값과 접속 주소를 임의 생성하지 않는다. writeOnly:true를 민감 설정의 기본 표시로 사용하고 민감 키·접속 주소 식별은 보조 수단으로 적용한다. 복합 스키마의 기본값을 추론하지 않고, 없는 선택 object를 자식 기본값만으로 만들지 않는다. 런타임 검증은 기본값 삽입·형 변환·필드 삭제를 하지 않는다.
 
-성공한 변경 명령은 stdout에 changed/preserved JSON을 출력한다. 실패는 종료 코드 1과 stderr로 보고한다. dry-run도 다운로드·임시 설치 비용이 들 수 있다. 사용자 수정 파일은 제거 시 보존하고 역의존 플러그인이 있으면 제거를 차단한다.
+새 플러그인의 설정 준비 후 오류가 필수값 누락(required)뿐이면 설치를 완료하고 configRequired로 미완료 설정을 알린다. 표시 오류는 최대20개이며 전체 errorCount를 제공한다. doctor와 앱 실행은 값이 채워질 때까지 실패한다. 타입·범위·추가 키·복합 조건 오류 또는 기존 플러그인의 설정 오류는 설치를 차단한다. allErrors 검사로 required 뒤의 다른 오류를 숨기지 않는다.
 
-설치 스크립트는 실행하지 않는다. 앱 실행 시에는 플러그인 코드가 실행되므로 신뢰할 패키지만 사용한다. 업그레이드·기존 임의 앱 가져오기·workspace·git/URL 의존성·강제 종료 자동 복구는 지원하지 않는다. MIT 라이선스다. Node 24는 macOS 및 Linux amd64 CI에서 검증했고 Windows 및 OS별 전역 설치는 미검증이다.
+제거 후에도 사용자 옵션은 보존하며 앱 설정으로 사용할 수 있는 미등록 키를 임의로 삭제하지 않는다. 생성 진입점은 YAML 로딩 → Application 생성 → 전체 옵션 검증 → 플러그인 생성·등록 → 앱 시작 순서다. 팩토리의 app과 setup/start의 context.app에는 동일한 ApplicationView를 전달한다. 뷰는 앱별로 한 번 만들고 동결하며 config와 logger만 제공한다. 뷰에 start·stop·register·get은 없다. context.logger는 플러그인 문맥, context.app.logger는 앱 문맥 로거다. 기존 팩토리 options·dependencies 전달은 호환을 위해 유지한다.
 
-자세한 계약과 예제: [Dokebi 저장소](https://git.nyx-zone.com/dokebi/framework).
+## JSON 프로젝트 이전
 
-<!-- [AI:수정] AI용 CLI 계약과 검증 완료 상태·남은 배포 작업을 문서에 연결한다. -->
-AI·자동화 작업은 [동봉된 사용 계약](AI.md)을 참고한다. inspect --json과 doctor --json으로 실제 설치 상태와 플러그인별 옵션 스키마·문서 위치를 확인한다. init은 생성 앱에 짧은 AGENTS.md를 추가한다.
+migrate는 0.2.0 이상 코어가 필요하다. YAML·JSON이 동시에 있으면 충돌로 중단하며 병합하지 않는다. JSON 원본은 .dokebi/dokebi.json.backup에 0600 권한으로 보존하고 활성 JSON은 제거한다. 기존 백업을 덮어쓰지 않는다. 생성 등록 코드·Git 제외·기본 진입점을 트랜잭션으로 갱신한다.
 
-## npm 설치
+사용자가 수정한 진입점은 자동 추측해 덮어쓰지 않는다. CLI가 안내하는 새 로딩·등록 흐름에 맞춰 명시적으로 이전해야 한다. 정확한 지원 조건과 오류를 확인하고 실패 후 무조건 재시도하거나 잠금·백업을 삭제하지 않는다.
 
-npm에서 0.1.1이 공개되면 다음 명령으로 설치한다.
+사용자 수정 템플릿은 제거 시 보존한다. 설치 스크립트는 실행하지 않지만 앱 실행 시 패키지 코드는 실행하므로 신뢰할 플러그인을 사용한다. 임의 업그레이드·workspace·git/URL 의존성·강제 종료 자동 복구는 지원하지 않는다. Windows와 운영 안정화의 미검증 범위는 저장소 기록을 따른다.
 
-```sh
-npm install --save-dev @dokebi/cli@0.1.1
-npx dokebi init ./my-app
-```
+MIT 라이선스. [AI 사용 계약](AI.md), [저장소](https://git.nyx-zone.com/dokebi/framework)를 참고한다.
+
+플러그인은 package.json의 `dokebi.install.directories`로 빈 폴더를, `dokebi.install.files`로 템플릿 복사를 선언할 수 있다. 대상은 예약 파일을 제외한 `src/` 하위다. manifest schema 2는 `dokebi.install.entry`(사용자 진입 파일)와 `configDefaults`도 선언할 수 있고, schema 1의 최상위 `dokebi.files`는 읽기 호환으로만 병합한다. 스키마 기반 YAML 설정 준비를 함께 처리한다. 선언한 `installModule`의 `planInstall`·`planUpgrade`·`check`는 Node 권한 모델(쓰기·자식 프로세스 금지, 환경변수 없음)로 격리해 실행한다. npm lifecycle script는 실행하지 않는다. 상세는 [설치 생명주기](../../docs/cli/installation.md)다. 실패 시 생성한 빈 폴더를 되돌리고 remove 시 폴더는 보존한다.

package/dist/bin.js

@@ -1,16 +1,41 @@
 #!/usr/bin/env node
+import { parseSetOption } from './config-edit.js';
 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 HELP = 'dokebi init <directory> [--core <package|local.tgz>] [--json]\ndokebi add <package|local.tgz> [--set <path>=<value>]... [--dry-run] [--json]\ndokebi upgrade <plugin-id> [--to <version|package|local.tgz>] [--dry-run] [--json]\ndokebi remove <plugin-id> [--dry-run] [--json]\ndokebi migrate [--dry-run] [--json]\ndokebi inspect [--json]\ndokebi doctor [--json]\ndokebi app add <name> [--domain <host>]... [--template <name>] [--inertia] [--dry-run] [--json]\ndokebi app remove <name> [--dry-run] [--json]\ndokebi app link <name> <domain> [--template <name>] [--dry-run] [--json]\ndokebi app unlink <domain> [--dry-run] [--json]\ndokebi app list [--json]\ndokebi module add <name> [--no-views] [--dry-run] [--json]\ndokebi module remove <name> [--dry-run] [--json]\ndokebi module list [--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;
+/** Splits repeatable `--set` and single-valued flags; anything else is a usage error. */
+function flags(input, allowed) {
+    let dryRun = false;
+    let to;
+    const sets = [];
+    for (let index = 0; index < input.length; index++) {
+        const arg = input[index];
+        if (arg === '--dry-run' && !dryRun)
+            dryRun = true;
+        else if (arg === '--set' && allowed.set) {
+            const value = input[++index];
+            if (value === undefined || value.startsWith('--'))
+                throw new CliError('USAGE', HELP);
+            sets.push(parseSetOption(value));
+        }
+        else if (arg === '--to' && allowed.to && to === undefined) {
+            const value = input[++index];
+            if (!value || value.startsWith('-'))
+                throw new CliError('USAGE', HELP);
+            to = value;
+        }
+        else
+            throw new CliError('USAGE', HELP);
+    }
+    return { dryRun, sets, to };
+}
 async function main() {
     if (raw.filter((arg) => arg === '--json').length > 1)
         throw new CliError('USAGE', HELP);
@@ -26,13 +51,31 @@ async function main() {
     if (command === 'inspect' || command === 'doctor') {
         if (args.length)
             throw new CliError('USAGE', HELP);
-        const result = await new ProjectInspector().inspect(process.cwd());
+        const result = await new ProjectInspector().inspect(process.cwd(), {
+            runChecks: command === 'doctor',
+        });
         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;
     }
+    if (command === 'migrate') {
+        if (args.length && (args.length !== 1 || args[0] !== '--dry-run'))
+            throw new CliError('USAGE', HELP);
+        mutationStarted = true;
+        const result = await new Project().migrate(process.cwd(), args[0] === '--dry-run');
+        process.stdout.write(JSON.stringify(machine ? envelope(command, result) : result, null, 2) + '\n');
+        return;
+    }
+    if (command === 'app') {
+        await app(args);
+        return;
+    }
+    if (command === 'module') {
+        await moduleCommand(args);
+        return;
+    }
     const target = args.shift();
     if (!target || target.startsWith('-'))
         throw new CliError('USAGE', HELP);
@@ -45,20 +88,166 @@ async function main() {
         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);
+    else if (command === 'add') {
+        const options = flags(args, { set: true });
+        mutationStarted = true;
+        result = await project.add(process.cwd(), target, options.dryRun, options.sets);
+    }
+    else if (command === 'upgrade') {
+        const options = flags(args, { to: true });
         mutationStarted = true;
-        result = await project[command](process.cwd(), target, args[0] === '--dry-run');
+        result = await project.upgrade(process.cwd(), target, options.to, options.dryRun);
+    }
+    else if (command === 'remove') {
+        const options = flags(args, {});
+        mutationStarted = true;
+        result = await project.remove(process.cwd(), target, options.dryRun);
     }
     else
         throw new CliError('USAGE', HELP);
+    if (!machine)
+        for (const warning of result.warnings ?? [])
+            if (warning.code === 'SECRET_ON_COMMAND_LINE')
+                process.stderr.write(`warning: ${warning.path} looks secret; command-line values can remain in shell history\n`);
     process.stdout.write(JSON.stringify(machine ? envelope(command, result) : result, null, 2) + '\n');
 }
+/** `dokebi app add|remove|list` (D-0030): apps of @dokebi/app and their domains. */
+async function app(input) {
+    const action = input.shift();
+    const project = new Project();
+    let result;
+    if (action === 'list') {
+        if (input.length)
+            throw new CliError('USAGE', HELP);
+        result = await project.appList(process.cwd());
+    }
+    else if (action === 'add' || action === 'remove') {
+        const name = input.shift();
+        if (!name || name.startsWith('-'))
+            throw new CliError('USAGE', HELP);
+        let dryRun = false;
+        let inertia = false;
+        let template;
+        const domains = [];
+        for (let index = 0; index < input.length; index++) {
+            const arg = input[index];
+            const value = input[index + 1];
+            if (arg === '--dry-run' && !dryRun)
+                dryRun = true;
+            else if (action === 'add' && arg === '--inertia' && !inertia)
+                inertia = true;
+            else if (action === 'add' && arg === '--domain' && value && !value.startsWith('-')) {
+                domains.push(value);
+                index++;
+            }
+            else if (action === 'add' && arg === '--template' && value && !template) {
+                template = value;
+                index++;
+            }
+            else
+                throw new CliError('USAGE', HELP);
+        }
+        mutationStarted = true;
+        result =
+            action === 'add'
+                ? await project.appAdd(process.cwd(), name, {
+                    domains,
+                    dryRun,
+                    inertia,
+                    ...(template ? { template } : {}),
+                })
+                : await project.appRemove(process.cwd(), name, dryRun);
+    }
+    else if (action === 'link' || action === 'unlink') {
+        const first = input.shift();
+        const domain = action === 'link' ? input.shift() : first;
+        if (!first || first.startsWith('-') || !domain || domain.startsWith('-'))
+            throw new CliError('USAGE', HELP);
+        let dryRun = false;
+        let template;
+        for (let index = 0; index < input.length; index++) {
+            const arg = input[index];
+            const value = input[index + 1];
+            if (arg === '--dry-run' && !dryRun)
+                dryRun = true;
+            else if (action === 'link' && arg === '--template' && value && !template) {
+                template = value;
+                index++;
+            }
+            else
+                throw new CliError('USAGE', HELP);
+        }
+        mutationStarted = true;
+        result =
+            action === 'link'
+                ? await project.appLink(process.cwd(), first, domain, {
+                    dryRun,
+                    ...(template ? { template } : {}),
+                })
+                : await project.appUnlink(process.cwd(), domain, dryRun);
+    }
+    else
+        throw new CliError('USAGE', HELP);
+    process.stdout.write(JSON.stringify(machine ? envelope(`app ${action}`, result) : result, null, 2) + '\n');
+}
+/** `dokebi module add|remove|list` (D-0032): feature modules in src/shared/modules/<name>. */
+async function moduleCommand(input) {
+    const action = input.shift();
+    const project = new Project();
+    let result;
+    if (action === 'list') {
+        if (input.length)
+            throw new CliError('USAGE', HELP);
+        result = await project.moduleList(process.cwd());
+    }
+    else if (action === 'add' || action === 'remove') {
+        const name = input.shift();
+        if (!name || name.startsWith('-'))
+            throw new CliError('USAGE', HELP);
+        let dryRun = false;
+        let views = true;
+        for (const arg of input) {
+            if (arg === '--dry-run' && !dryRun)
+                dryRun = true;
+            else if (action === 'add' && arg === '--no-views' && views)
+                views = false;
+            else
+                throw new CliError('USAGE', HELP);
+        }
+        mutationStarted = true;
+        result =
+            action === 'add'
+                ? await project.moduleAdd(process.cwd(), name, { views, dryRun })
+                : await project.moduleRemove(process.cwd(), name, dryRun);
+    }
+    else
+        throw new CliError('USAGE', HELP);
+    process.stdout.write(JSON.stringify(machine ? envelope(`module ${action}`, 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.stderr.write((error instanceof CliError ? error.code + ': ' + error.message : String(error)) +
+            '\n' +
+            nextSteps(error));
     process.exitCode = 1;
 });
+/** Human-readable follow-ups from error details: missing option fields and plugin hints. */
+function nextSteps(error) {
+    if (!(error instanceof CliError) || !error.details || typeof error.details !== 'object')
+        return '';
+    const details = error.details;
+    const lines = new Set();
+    if (Array.isArray(details.errors))
+        for (const item of details.errors)
+            if (typeof item?.missingProperty === 'string')
+                lines.add(`missing: options.${String(details.plugin)}${String(item.instancePath ?? '').replaceAll('/', '.')}.${item.missingProperty}`);
+    if (error.code === 'WORKSPACE_SYNC_FAILED')
+        lines.add('hint: run npm install at the workspace root');
+    if (Array.isArray(details.diagnostics))
+        for (const item of details.diagnostics)
+            if (typeof item?.hint === 'string')
+                lines.add(`hint: ${item.hint}`);
+    return [...lines].map((line) => line + '\n').join('');
+}

package/dist/config-edit.d.ts

@@ -0,0 +1,19 @@
+import type { ConfigChange } from './plugin-lifecycle.js';
+export interface SetOption {
+    readonly path: string[];
+    readonly value: unknown;
+}
+export interface Warning {
+    code: string;
+    path?: string;
+}
+/** Parses one `--set <path>=<value>` argument. Values are JSON when parseable, otherwise text. */
+export declare function parseSetOption(argument: string): SetOption;
+export declare function setWarnings(sets: readonly SetOption[]): Warning[];
+export declare function applySetOptions(source: string, id: string, sets: readonly SetOption[]): string;
+export declare function applyConfigChanges(source: string, id: string, changes: readonly ConfigChange[]): string;
+/** Keeps a removed plugin's section and marks it for a later reinstall or manual cleanup. */
+export declare function markRemoved(source: string, id: string): {
+    source: string;
+    marked: boolean;
+};

package/dist/config-edit.js

@@ -0,0 +1,124 @@
+import { isDeepStrictEqual } from 'node:util';
+import { isMap, isNode, isScalar, parseDocument } from 'yaml';
+import { parseProjectConfig, renderConfig } from './configuration.js';
+import { CliError } from './errors.js';
+import { validateDefaults } from './merge-install-defaults.js';
+const SEGMENT = /^[A-Za-z0-9_-]{1,64}$/;
+const FORBIDDEN = new Set(['__proto__', 'constructor', 'prototype', '<<']);
+const SECRET = /(password|passwd|secret|token|credential|api.?key|private.?key)/i;
+/** Parses one `--set <path>=<value>` argument. Values are JSON when parseable, otherwise text. */
+export function parseSetOption(argument) {
+    const index = argument.indexOf('=');
+    if (index <= 0)
+        throw new CliError('INVALID_SET', 'Use --set <path>=<value>');
+    const path = argument.slice(0, index).split('.');
+    if (path.length > 16 || path.some((key) => !SEGMENT.test(key) || FORBIDDEN.has(key)))
+        throw new CliError('INVALID_SET', 'Invalid --set path');
+    const text = argument.slice(index + 1);
+    let value = text;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        /* plain text value */
+    }
+    try {
+        validateDefaults({ value });
+    }
+    catch {
+        throw new CliError('INVALID_SET', 'Invalid --set value');
+    }
+    return { path, value };
+}
+export function setWarnings(sets) {
+    return sets
+        .filter((set) => set.path.some((key) => SECRET.test(key)))
+        .map((set) => ({ code: 'SECRET_ON_COMMAND_LINE', path: set.path.join('.') }));
+}
+function ensureMap(document, path, code) {
+    for (let length = 1; length <= path.length; length++) {
+        const current = path.slice(0, length);
+        const node = document.getIn(current, true);
+        if (!document.hasIn(current) || (isScalar(node) && node.value === null))
+            document.setIn(current, document.createNode({}));
+        else if (!isMap(node))
+            throw new CliError(code, 'Configuration path crosses a non-mapping value');
+    }
+}
+/** Applies an edit inside options.<id> and proves no other plugin section changed. */
+function edit(source, id, apply) {
+    const before = parseProjectConfig(source);
+    const document = parseDocument(source, { version: '1.2' });
+    ensureMap(document, ['options', id], 'INVALID_CONFIG');
+    apply(document);
+    const result = renderConfig(document);
+    const after = parseProjectConfig(result);
+    for (const key of new Set([...Object.keys(before.options), ...Object.keys(after.options)]))
+        if (key !== id && !isDeepStrictEqual(before.options[key], after.options[key]))
+            throw new CliError('INVALID_CONFIG', 'Configuration edit escaped its plugin section');
+    return result;
+}
+export function applySetOptions(source, id, sets) {
+    const seen = new Set();
+    for (const set of sets) {
+        const key = set.path.join('.');
+        if (seen.has(key))
+            throw new CliError('INVALID_SET', 'Repeated --set path');
+        seen.add(key);
+    }
+    return edit(source, id, (document) => {
+        for (const set of sets) {
+            const path = ['options', id, ...set.path];
+            ensureMap(document, path.slice(0, -1), 'INVALID_SET');
+            document.setIn(path, document.createNode(set.value));
+        }
+    });
+}
+export function applyConfigChanges(source, id, changes) {
+    if (!changes.length)
+        return source;
+    return edit(source, id, (document) => {
+        const base = ['options', id];
+        for (const change of changes) {
+            if (change.op === 'rename' && change.from && change.to) {
+                const from = [...base, ...change.from];
+                const to = [...base, ...change.to];
+                if (!document.hasIn(from))
+                    continue;
+                if (document.hasIn(to))
+                    throw new CliError('UPGRADE_CONFIG_CONFLICT', 'Renamed option already exists');
+                const node = document.getIn(from, true);
+                ensureMap(document, to.slice(0, -1), 'UPGRADE_CONFIG_CONFLICT');
+                document.deleteIn(from);
+                document.setIn(to, isNode(node) ? node : document.createNode(node));
+            }
+            else if (change.op === 'remove' && change.path) {
+                // Removing a path that does not exist (also below a null value) changes nothing.
+                const path = [...base, ...change.path];
+                if (document.hasIn(path))
+                    document.deleteIn(path);
+            }
+            else if (change.op === 'default' && change.path) {
+                const path = [...base, ...change.path];
+                if (document.hasIn(path))
+                    continue;
+                validateDefaults({ value: change.value });
+                ensureMap(document, path.slice(0, -1), 'UPGRADE_CONFIG_CONFLICT');
+                document.setIn(path, document.createNode(change.value));
+            }
+        }
+    });
+}
+/** Keeps a removed plugin's section and marks it for a later reinstall or manual cleanup. */
+export function markRemoved(source, id) {
+    const document = parseDocument(source, { version: '1.2' });
+    const node = document.getIn(['options', id], true);
+    if (!isNode(node))
+        return { source, marked: false };
+    const marker = `[dokebi:${id}] removed; kept for reinstall`;
+    if (!node.commentBefore?.includes(marker))
+        node.commentBefore = (node.commentBefore ? node.commentBefore + '\n' : '') + marker;
+    const result = renderConfig(document);
+    parseProjectConfig(result);
+    return { source: result, marked: true };
+}

package/dist/configuration-scaffold.d.ts

@@ -0,0 +1 @@
+export declare function scaffoldConfig(source: string, id: string, schema: Record<string, unknown> | null): string;