@dokebi/cli 0.2.3 → 0.2.4

package/AI.md

@@ -1,4 +1,4 @@
-# AI 작업 안내 — @dokebi/cli 0.2.3 (`dokebi`)
+# AI 작업 안내 — @dokebi/cli 0.2.4 (`dokebi`)
 
 도깨비 프로젝트를 만들고 플러그인·앱·모듈을 설치·제거·업그레이드하는 명령이다. 프로젝트가 가진 「CLI 소유 파일」(생성 등록 코드, 상태, 견본 설정)을 트랜잭션으로 고친다. AI는 이 파일들을 손으로 편집하지 말고 반드시 명령으로 바꾼다. 명령 세부 정의는 [docs/cli/README.md](../../docs/cli/README.md), 설치 생명주기는 [docs/cli/installation.md](../../docs/cli/installation.md), 자동화 계약은 [docs/cli/automation.md](../../docs/cli/automation.md)다.
 
@@ -18,8 +18,8 @@
 | `dokebi app add <이름> [--domain <host>]... [--template <이름>] [--inertia [--ssr]]` | `src/apps/<이름>` 앱(D-0030). `--inertia`는 Vue 골격과 Vite 빌드 준비, `--ssr`은 서버 렌더링 준비(D-0039) |
 | `dokebi app remove <이름>` · `app link <앱> <도메인> [--template]` · `app unlink <도메인>` · `app list` | 앱·도메인 관리 |
 | `dokebi module add <이름> [--no-views]` · `module remove` · `module list` | `src/shared/modules/<이름>` 기능 모듈(D-0032) |
-| `dokebi dev` | 개발 실행(앞에서). `src/`·`dokebi.yaml`·`.env`가 바뀌면 drain 뒤 다시 띄움. Vite 설정이 있고 template-inertia ≥0.1.2면 `DOKEBI_VITE_DEV=1`로 Vite 개발 서버를 앱 안에 띄워 **HMR**(빌드 불필요, `.vue`·`views/` 변경은 재시작 없음, D-0045). 옛 template-inertia면 감시 빌드 + 재시작(다음 판, D-0044) |
-| `dokebi start [--foreground] [--wait-ms <ms>]` · `stop [--timeout-ms <ms>] [--force]` · `status` · `logs [-n <줄>] [-f]` | 백그라운드 실행·종료·상태·로그(아래 §2.1, 다음 판, D-0044) |
+| `dokebi dev` | 개발 실행(앞에서). `src/`·`dokebi.yaml`·`.env`가 바뀌면 drain 뒤 다시 띄움. Vite 설정이 있고 template-inertia ≥0.1.2면 `DOKEBI_VITE_DEV=1`로 Vite 개발 서버를 앱 안에 띄워 **HMR**(빌드 불필요, `.vue`·`views/` 변경은 재시작 없음, D-0045). 옛 template-inertia면 감시 빌드 + 재시작. 띄운 앱에 `DOKEBI_DEV=1`을 넣어 cluster 앱은 워커 1개로 돈다(`DOKEBI_DEV_WORKERS`, D-0044·D-0045) |
+| `dokebi start [--foreground] [--wait-ms <ms>] [--log-max-mb <MB>] [--log-files <n>]` · `stop [--timeout-ms <ms>] [--force]` · `status` · `logs [-n <줄>] [-f]` | 백그라운드 실행·종료·상태·로그와 로그 회전(아래 §2.1, 다음 판, D-0044·D-0053) |
 
 모든 명령에 `--json`(기계용 단일 문서)과 변경 명령에 `--dry-run`(계획만)이 있다.
 
@@ -34,13 +34,14 @@
 
 ## 2.1 서버 실행(D-0044, 다음 판)
 
-- 한 프로젝트 = 프로세스 하나(`src/main.ts`, 여러 앱도 같은 프로세스). 실행 파일은 `.dokebi/run/`(`app.pid`, `app.log`, 안의 `.gitignore`가 `*`라 Git에 안 들어간다).
-- `start`: inspect와 같은 검사(error 진단이 있으면 `START_CHECK_FAILED`) 뒤 `NODE_ENV=production`(이미 정해져 있으면 그대로)으로 백그라운드 실행. 로그에 `Dokebi application started`(생성된 main이 쓰는 줄)가 찍히면 `ready: true`. `--wait-ms`(기본 10000) 안에 그 줄이 없으면 살아 있어도 `ready: false`와 경고. 그 전에 끝나면 `START_FAILED`(details.tail에 로그 끝 30줄). 이미 실행 중이면 `ALREADY_RUNNING`, 다른 start가 진행 중이면 `START_IN_PROGRESS`.
-- `stop`: SIGTERM으로 drain. `--timeout-ms`(기본 30000) 안에 안 끝나면 `STOP_TIMEOUT`(프로세스는 그대로), `--force`면 그때 SIGKILL. 실행 중이 아니면 `stopped: false`.
-- `status`: 실행 중이면 pid·가동 초·RSS. 멈춤이면 **종료 코드 3**. PID 파일만 남은 경우(밖에서 죽음·crash)는 `stale: true`로 알리고 파일을 지운다.
+- 한 프로젝트 = 프로세스 하나(`src/main.ts`, 여러 앱도 같은 프로세스). 실행 파일은 `.dokebi/run/`(`app.pid`, `app.log`·`app.log.1`…, `log-writer.log`, 안의 `.gitignore`가 `*`라 Git에 안 들어간다).
+- **로그 회전(D-0053)**: `start`는 분리된 로그 기록 프로세스(log writer)를 띄우고, 기록기가 앱을 stdout·stderr 파이프로 띄워 줄 단위로 `app.log`에 쓴다. 다음 줄이 `--log-max-mb`(기본 50, 1–10240)를 넘기면 줄 경계에서 `app.log.1`로 밀고 `--log-files`(기본 5, 1–100)개만 남긴다. 빠르게 써도 줄을 잃지 않는다(디스크가 느리면 앱 쓰기가 기다림). 범위 밖은 `USAGE`, `--foreground`와 함께 쓰면 `USAGE`. dokebi.yaml 설정은 없다(매번 같은 값은 package.json 스크립트에). 기록기는 SIGTERM을 무시하고 앱이 끝나면(crash 포함) `--- dokebi: app exited (…) ---` 한 줄을 쓰고 끝난다. 기록기 자신의 오류는 `.dokebi/run/log-writer.log`에 JSON 한 줄(`level: error`·`code`·전체 `error`): `LOG_OPEN_FAILED`, `LOG_WRITE_FAILED`, `LOG_ROTATE_FAILED`, `LOG_LINES_DROPPED`, `APP_SPAWN_FAILED`, `APP_OUTPUT_FAILED`.
+- `start`: inspect와 같은 검사(error 진단이 있으면 `START_CHECK_FAILED`) 뒤 `NODE_ENV=production`(이미 정해져 있으면 그대로)으로 백그라운드 실행. 로그에 `Dokebi application started`(생성된 main이 쓰는 줄)가 지나가면 `ready: true`. 결과에 `logWriter`(pid)·`logMaxBytes`·`logFiles`. `--wait-ms`(기본 10000) 안에 그 줄이 없으면 살아 있어도 `ready: false`와 경고. 그 전에 끝나면 `START_FAILED`(details.tail에 로그 끝 30줄, details.logWriterLog에 기록기 진단 끝). 이미 실행 중이면 `ALREADY_RUNNING`, 다른 start가 진행 중이면 `START_IN_PROGRESS`.
+- `stop`: **앱에** SIGTERM으로 drain(기록기는 앱 출력이 끝나면 따라 끝나고, 5초 안에 안 끝나면 `warnings`). `--timeout-ms`(기본 30000) 안에 안 끝나면 `STOP_TIMEOUT`(프로세스는 그대로), `--force`면 그때 SIGKILL. 실행 중이 아니면 `stopped: false`.
+- `status`: 실행 중이면 pid·가동 초·RSS·`logWriter: { pid, running }`(running false면 앱 출력이 기록되지 않는 상태). 항상 `logFiles`(app.log와 회전 파일, 새것부터, `{ file, bytes }`), 기록기 진단이 있으면 `logWriterLog`. 멈춤이면 **종료 코드 3**. PID 파일만 남은 경우(밖에서 죽음·crash)는 `stale: true`로 알리고 파일을 지운다.
 - PID는 재사용되므로 `ps`로 그 pid의 명령줄에 이 프로젝트의 `src/main.ts`가 있고 시작 시각이 맞을 때만 신호를 보낸다. 아니면 낡은 PID 파일로 본다.
-- `logs`: 마지막 `-n`(기본 100)줄, `-f`는 Ctrl+C까지 따라 읽기. 로그 회전은 없다(100MB를 넘으면 start가 경고). `logs`·`dev`·`start --foreground`는 `--json`이 없다.
-- 하지 않는 것: crash 뒤 자동 재시작, 부팅 시 시작, 로그 회전. 운영 서버는 systemd·Docker에서 `dokebi start --foreground`(또는 `node src/main.ts`)를 쓰는 편이 낫다. Windows는 `start`(백그라운드)·`stop`이 `UNSUPPORTED_PLATFORM`.
+- `logs`: 마지막 `-n`(기본 100)줄(모자라면 `app.log.1`·`.2`…에서 앞을 채움), `-f`는 Ctrl+C까지 따라 읽기(읽던 파일을 inode로 기억해, 회전되면 옛 파일 끝까지 읽고 그보다 새 회전 파일을 오래된 것부터 읽은 뒤 새 `app.log`로 넘어감 — 확인 주기 250ms 사이에 회전이 여러 번 일어나도 줄을 건너뛰지 않는다. 처음 `-n` 줄과 따라 읽기 사이에도 빈틈이 없다. 읽던 파일이 `--log-files` 밖으로 지워질 만큼 뒤처지면 `--- dokebi: logs -f fell behind … ---` 한 줄을 찍고 남은 가장 오래된 파일부터 잇는다). `logs`·`dev`·`start --foreground`는 `--json`이 없다.
+- 하지 않는 것: crash 뒤 자동 재시작, 부팅 시 시작, 시간 기준 회전·압축. 운영 서버는 systemd·Docker에서 `dokebi start --foreground`(또는 `node src/main.ts`)를 쓰는 편이 낫다. Windows는 `start`(백그라운드)·`stop`이 `UNSUPPORTED_PLATFORM`.
 - `src/main.ts`를 고쳐 시작 줄을 지우면 start가 준비 여부를 알 수 없다. 남겨 둔다.
 
 ## 3. JSON 출력
@@ -84,7 +85,13 @@ npm 워크스페이스 구성원 폴더에서도 모든 명령이 된다. 패키
 ## 8. 주요 오류·진단 코드
 
 - 명령: `USAGE`, `PROJECT_EXISTS`, `UNSUPPORTED_PROJECT`, `INVALID_SPEC`, `INVALID_PACKAGE`, `INVALID_MANIFEST`, `INCOMPATIBLE_VERSION`, `MISSING_DEPENDENCY`, `DEPENDENCY_CYCLE`, `DUPLICATE_PLUGIN`, `UNKNOWN_PLUGIN`, `REVERSE_DEPENDENCY`, `REQUIRED_PLUGIN`, `INVALID_PLUGIN_OPTIONS`, `INVALID_SET`, `FILE_CONFLICT`, `PATH_CONFLICT`, `PACKAGE_CONFLICT`, `NPM_FAILED`, `CONCURRENT_CHANGE`, `COMMIT_FAILED`, `UPGRADE_DOWNGRADE`, `UPGRADE_IDENTITY_CHANGED`, `UPGRADE_ENTRY_MOVED`, `UPGRADE_CONFIG_CONFLICT`, `APP_EXISTS`, `APP_IN_USE`, `APPS_PRESENT`, `APP_PLUGIN_MISSING`, `DOMAIN_IN_USE`, `UNKNOWN_APP`, `UNKNOWN_DOMAIN`, `MODULE_EXISTS`, `MODULE_PLUGIN_MISSING`, `UNKNOWN_MODULE`, 서버 명령 `ENTRY_MISSING`, `START_CHECK_FAILED`, `ALREADY_RUNNING`, `START_IN_PROGRESS`, `START_FAILED`, `STOP_TIMEOUT`, `NO_LOG`, `UNSUPPORTED_PLATFORM`.
-- 진단(inspect·doctor): `MIGRATION_REQUIRED`, `CONFIG_CONFLICT`, `INVALID_CORE`, `PACKAGE_VERSION_MISMATCH`, `MISSING_CORE_DEPENDENCY`, `MISSING_PACKAGE_DEPENDENCY`, `MODIFIED_REGISTRATION`, `MODIFIED_TEMPLATE`, `MANIFEST_CHANGED`, `INVALID_PLUGIN_OPTIONS`, `ENTRY_MISSING`, `LEGACY_LAYOUT`, `MISSING_REQUIRED_PLUGIN`, `STALE_REQUIREMENTS`, `PLUGIN_CHECK`, `PROJECT_LOCKED`, `RECOVERY_REQUIRED`, `UNSAFE_PATH`.
+- 진단(inspect·doctor): `MIGRATION_REQUIRED`, `CONFIG_CONFLICT`, `INVALID_CORE`, `PACKAGE_VERSION_MISMATCH`, `MISSING_CORE_DEPENDENCY`, `MISSING_PACKAGE_DEPENDENCY`, `MODIFIED_REGISTRATION`, `MODIFIED_TEMPLATE`, `MANIFEST_CHANGED`, `INVALID_PLUGIN_OPTIONS`, `ENTRY_MISSING`, `LEGACY_LAYOUT`, `MISSING_REQUIRED_PLUGIN`, `STALE_REQUIREMENTS`, `PLUGIN_CHECK`, `PROJECT_LOCKED`, `RECOVERY_REQUIRED`, `UNSAFE_PATH`, `INVALID_LOGGING_CONFIG`(error: `options.logging`의 수준 값·키), `LOGGING_PLUGIN_UNKNOWN`(warning: 설치되지 않은 플러그인의 수준).
+
+### 로그(D-0047)
+
+- `init`이 쓰는 dokebi.yaml·dokebi.example.yaml에는 `options.logging: { level: info }`와 주석으로 된 `plugins` 예가 있다. `options.logging`은 core가 읽는 로그 설정이고 플러그인 옵션이 아니다. 기존 프로젝트는 자동으로 바꾸지 않는다(필요하면 직접 추가).
+- 실행 중 수준은 `DOKEBI_LOG_LEVEL`이 yaml보다 우선한다(`DOKEBI_LOG_LEVEL=debug npx dokebi dev`).
+- CLI 자신도 `DOKEBI_LOG_LEVEL=debug`이면 npm 실행·설치 모듈·트랜잭션 되돌림·start/stop의 결정을 stderr에 JSON 한 줄씩 남긴다. 복구하고 넘어가는 오류(읽을 수 없는 pid 파일·워크스페이스 package.json 등)는 수준과 상관없이 stderr에 `level: error` 한 줄(`code`·`error`)로 남긴다. stdout(`--json` 봉투)은 바뀌지 않는다.
 - 경고: `BUILD_SCRIPT_KEPT`, `INERTIA_PLUGIN_MISSING`, `SECRET_ON_COMMAND_LINE`, `EXAMPLE_MISSING`, `EXAMPLE_INVALID`.
 
 ## 9. 주의 사항
@@ -99,4 +106,4 @@ npm 워크스페이스 구성원 폴더에서도 모든 명령이 된다. 패키
 ## 10. 근거
 
 - 예제: `examples/06-cli`, `26-scaffold`(실제 CLI로 같은 프로젝트를 반복 생성·빌드·실행), `25-playground`(`tools/regenerate.ts`가 CLI 기록 전체를 재생).
-- 결정: D-0009·D-0011·D-0012(설정), D-0028(manifest schema 2), D-0030~D-0032(앱·구조·모듈), D-0035(워크스페이스), D-0037(manifest 판), D-0039(SSR), D-0044(서버 명령).
+- 결정: D-0009·D-0011·D-0012(설정), D-0028(manifest schema 2), D-0030~D-0032(앱·구조·모듈), D-0035(워크스페이스), D-0037(manifest 판), D-0039(SSR), D-0044(서버 명령), D-0053(로그 회전).

package/README.md

@@ -1,6 +1,6 @@
 # @dokebi/cli
 
-Dokebi 프로젝트 생성과 플러그인 설치 도구 0.2.3이다. 명령은 dokebi다. 0.1.1과 달라진 점(YAML 설정, migrate, 멀티 앱·모듈 명령)은 CHANGELOG에 있다. Node.js >=24.0.0, ESM을 지원하며 기본 CI는 Node 24다.
+Dokebi 프로젝트 생성과 플러그인 설치 도구 0.2.4이다. 명령은 dokebi다. 0.1.1과 달라진 점(YAML 설정, migrate, 멀티 앱·모듈 명령)은 CHANGELOG에 있다. Node.js >=24.0.0, ESM을 지원하며 기본 CI는 Node 24다.
 
 ## 프로젝트와 명령
 
@@ -13,7 +13,7 @@ Dokebi 프로젝트 생성과 플러그인 설치 도구 0.2.3이다. 명령은
 - dokebi migrate [--dry-run] [--json]: 기존 JSON 프로젝트를 YAML 계약으로 명시적으로 이전한다.
 - dokebi inspect --json, dokebi doctor --json: 설치 버전·매니페스트·스키마·설정 문제를 읽기 전용으로 확인한다.
 - dokebi dev: 코드·설정이 바뀌면 다시 띄우는 개발 실행(Vite 설정이 있으면 `vite build --watch` 함께).
-- dokebi start [--foreground] · stop [--force] · status · logs [-n 줄] [-f]: 백그라운드 실행·종료·상태·로그. `.dokebi/run/app.pid`·`app.log`를 쓴다. 자동 재시작·로그 회전은 하지 않으므로 운영은 systemd·Docker에서 `start --foreground`를 권한다([D-0044](../../docs/decisions/D-0044-cli-server-commands.md), 다음 판).
+- dokebi start [--foreground] [--log-max-mb MB] [--log-files n] · stop [--force] · status · logs [-n 줄] [-f]: 백그라운드 실행·종료·상태·로그. `.dokebi/run/app.pid`·`app.log`를 쓴다. 로그는 분리된 기록 프로세스가 파이프로 받아 줄을 잃지 않고 크기로 회전한다(기본 50MB, `app.log.1`…`app.log.5`, [D-0053](../../docs/decisions/D-0053-cli-log-rotation.md)). `logs -n`은 회전된 파일까지 읽고 `-f`는 회전을 넘어 따라간다(확인 주기 사이에 여러 번 회전해도 inode로 가운데 파일까지 읽어 줄을 건너뛰지 않는다). 자동 재시작은 하지 않으므로 운영은 systemd·Docker에서 `start --foreground`를 권한다([D-0044](../../docs/decisions/D-0044-cli-server-commands.md), 다음 판).
 
 생성 앱의 npm start를 실행한다. 명령은 프로젝트 루트(또는 npm 워크스페이스 구성원 폴더)에서 설치된 CLI로 호출한다. 모든 명령에 `--json`이 있다. dry-run도 패키지 해석을 위해 다운로드·임시 설치할 수 있지만 관리 파일과 node_modules를 적용하지 않는다.
 

package/dist/bin.js

@@ -5,7 +5,7 @@ import { CLI_VERSION, envelope, failure } from './output.js';
 import { Project } from './project.js';
 import { ProjectInspector } from './project-inspector.js';
 import * as server from './server.js';
-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 [--ssr]] [--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]\ndokebi dev\ndokebi start [--foreground] [--wait-ms <ms>] [--json]\ndokebi stop [--timeout-ms <ms>] [--force] [--json]\ndokebi status [--json]\ndokebi logs [-n <lines>] [-f]\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 [--ssr]] [--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]\ndokebi dev\ndokebi start [--foreground] [--wait-ms <ms>] [--log-max-mb <MB>] [--log-files <n>] [--json]\ndokebi stop [--timeout-ms <ms>] [--force] [--json]\ndokebi status [--json]\ndokebi logs [-n <lines>] [-f]\n';
 const raw = process.argv.slice(2);
 const machine = raw.includes('--json');
 const args = raw.filter((arg) => arg !== '--json');
@@ -116,17 +116,22 @@ async function main() {
                 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');
 }
-/** Reads `--name <number>` style flags of the server commands; anything else is a usage error. */
+/**
+ * Reads `--name <number>` style flags of the server commands; anything else is a usage error.
+ * `numbers` maps each flag to its range (default 1 to 3600000).
+ */
 function serverFlags(input, numbers, switches) {
     const result = { numbers: new Map(), switches: new Set() };
     for (let index = 0; index < input.length; index++) {
         const arg = input[index];
         if (switches.includes(arg) && !result.switches.has(arg))
             result.switches.add(arg);
-        else if (numbers.includes(arg) && !result.numbers.has(arg)) {
-            const value = Number(input[++index]);
-            if (!Number.isSafeInteger(value) || value < 1 || value > 3_600_000)
-                throw new CliError('USAGE', HELP);
+        else if (Object.hasOwn(numbers, arg) && !result.numbers.has(arg)) {
+            const [min, max] = numbers[arg] ?? [1, 3_600_000];
+            const text = input[++index];
+            const value = Number(text);
+            if (text === undefined || !Number.isSafeInteger(value) || value < min || value > max)
+                throw new CliError('USAGE', `${arg} must be an integer from ${min} to ${max}\n${HELP}`);
             result.numbers.set(arg, value);
         }
         else
@@ -144,22 +149,38 @@ async function serverCommand(input) {
         process.exitCode = await server.dev(root, (line) => process.stderr.write(`[dokebi dev] ${line}\n`));
     }
     else if (command === 'start') {
-        const options = serverFlags(input, ['--wait-ms'], ['--foreground']);
+        const { maxMb, files } = server.LOG_LIMITS;
+        const options = serverFlags(input, {
+            '--wait-ms': undefined,
+            '--log-max-mb': [maxMb.min, maxMb.max],
+            '--log-files': [files.min, files.max],
+        }, ['--foreground']);
         if (options.switches.has('--foreground')) {
-            if (machine)
+            // The foreground app writes to the terminal; rotation belongs to systemd/Docker there.
+            if (machine || options.numbers.size)
                 throw new CliError('USAGE', HELP);
             process.exitCode = await server.foreground(root);
             return;
         }
-        const result = await server.start(root, options.numbers.get('--wait-ms'));
+        const megabytes = options.numbers.get('--log-max-mb');
+        const logFiles = options.numbers.get('--log-files');
+        const waitMs = options.numbers.get('--wait-ms');
+        const result = await server.start(root, {
+            ...(waitMs !== undefined ? { waitMs } : {}),
+            ...(megabytes !== undefined ? { logMaxBytes: megabytes * 1024 * 1024 } : {}),
+            ...(logFiles !== undefined ? { logFiles } : {}),
+        });
         if (!machine)
             for (const warning of result.warnings)
                 process.stderr.write(`warning: ${warning}\n`);
-        print(result, `started pid ${result.pid}${result.ready ? ` (ready in ${result.ms} ms)` : ''}\nlog: ${result.log}`);
+        print(result, `started pid ${result.pid}${result.ready ? ` (ready in ${result.ms} ms)` : ''}\nlog: ${result.log} (rotated at ${Math.round(result.logMaxBytes / 1048576)} MB, ${result.logFiles} older files kept)`);
     }
     else if (command === 'stop') {
-        const options = serverFlags(input, ['--timeout-ms'], ['--force']);
+        const options = serverFlags(input, { '--timeout-ms': undefined }, ['--force']);
         const result = await server.stop(root, options.numbers.get('--timeout-ms'), options.switches.has('--force'));
+        if (!machine)
+            for (const warning of result.warnings ?? [])
+                process.stderr.write(`warning: ${warning}\n`);
         print(result, result.stopped
             ? `stopped pid ${result.pid} in ${result.ms} ms${result.forced ? ' (killed)' : ''}`
             : result.stale
@@ -170,18 +191,29 @@ async function serverCommand(input) {
         if (input.length)
             throw new CliError('USAGE', HELP);
         const result = await server.status(root);
-        print(result, result.running
-            ? `running pid ${result.pid} · up ${result.uptimeSec} s · ${result.rssMb} MB\nlog: ${result.log}`
+        const files = result.logFiles
+            .map((file) => `\n  ${file.file} (${(file.bytes / 1048576).toFixed(1)} MB)`)
+            .join('');
+        const writer = result.logWriter
+            ? `\nlog writer: pid ${result.logWriter.pid}${result.logWriter.running ? '' : ' (not running: output is not being logged)'}`
+            : '';
+        const diagnostics = result.logWriterLog
+            ? `\nlog writer diagnostics: ${result.logWriterLog}`
+            : '';
+        print(result, (result.running
+            ? `running pid ${result.pid} · up ${result.uptimeSec} s · ${result.rssMb} MB${writer}`
             : result.stale
-                ? `stopped: pid ${result.pid} exited without dokebi stop (crashed or killed); see dokebi logs\nlog: ${result.log}`
-                : 'stopped');
+                ? `stopped: pid ${result.pid} exited without dokebi stop (crashed or killed); see dokebi logs`
+                : 'stopped') +
+            (files ? `\nlogs:${files}` : '') +
+            diagnostics);
         if (!result.running)
             process.exitCode = 3;
     }
     else {
         if (machine)
             throw new CliError('USAGE', HELP);
-        const options = serverFlags(input, ['-n'], ['-f', '--follow']);
+        const options = serverFlags(input, { '-n': undefined }, ['-f', '--follow']);
         await server.logs(root, options.numbers.get('-n'), options.switches.has('-f') || options.switches.has('--follow'));
     }
 }

package/dist/configuration-scaffold.js

@@ -89,6 +89,9 @@ export function scaffoldConfig(source, id, schema) {
             }
             if (!record(candidate))
                 continue;
+            // A deprecated option is still accepted (old files keep starting) but is not offered.
+            if (candidate.deprecated === true)
+                continue;
             const keys = [...path, name];
             const labels = [...names, name];
             const label = labels.map((key) => JSON.stringify(key)).join('.');

package/dist/configuration.d.ts

@@ -3,9 +3,9 @@ import { type ProjectConfig } from './project-state.js';
 export declare const CONFIG_FILE = "dokebi.yaml";
 export declare const LEGACY_CONFIG_FILE = "dokebi.json";
 export declare const CONFIG_BACKUP = ".dokebi/dokebi.json.backup";
-export declare const CONFIG_EXAMPLE = "# Copy to dokebi.yaml and keep actual credentials out of Git.\nschemaVersion: 1\noptions: {}\n";
+export declare const CONFIG_EXAMPLE = "# Copy to dokebi.yaml and keep actual credentials out of Git.\nschemaVersion: 1\noptions:\n  # Log level: debug, info, warn, error or silent. DOKEBI_LOG_LEVEL overrides it.\n  logging:\n    level: info\n    # Per-plugin levels by plugin name, louder or quieter than level:\n    # plugins:\n    #   dokebi-nats: debug\n";
 /** The real dokebi.yaml written by init: same shape, its own header. */
-export declare const CONFIG_TEMPLATE = "# Settings for this machine. Not committed to Git; dokebi.example.yaml is the shared sample.\nschemaVersion: 1\noptions: {}\n";
+export declare const CONFIG_TEMPLATE = "# Settings for this machine. Not committed to Git; dokebi.example.yaml is the shared sample.\nschemaVersion: 1\noptions:\n  # Log level: debug, info, warn, error or silent. DOKEBI_LOG_LEVEL overrides it.\n  logging:\n    level: info\n    # Per-plugin levels by plugin name, louder or quieter than level:\n    # plugins:\n    #   dokebi-nats: debug\n";
 /**
  * Serializes a configuration document edited by the CLI. Non-empty mappings and sequences under
  * `options` are written in block style, so schema comments and values stay readable even when the

package/dist/configuration.js

@@ -5,9 +5,18 @@ import { readConfig } from './project-state.js';
 export const CONFIG_FILE = 'dokebi.yaml';
 export const LEGACY_CONFIG_FILE = 'dokebi.json';
 export const CONFIG_BACKUP = '.dokebi/dokebi.json.backup';
-export const CONFIG_EXAMPLE = '# Copy to dokebi.yaml and keep actual credentials out of Git.\nschemaVersion: 1\noptions: {}\n';
+/** The logging block of a new project (D-0047): core reads options.logging, not a plugin. */
+const LOGGING_BLOCK = `options:
+  # Log level: debug, info, warn, error or silent. DOKEBI_LOG_LEVEL overrides it.
+  logging:
+    level: info
+    # Per-plugin levels by plugin name, louder or quieter than level:
+    # plugins:
+    #   dokebi-nats: debug
+`;
+export const CONFIG_EXAMPLE = `# Copy to dokebi.yaml and keep actual credentials out of Git.\nschemaVersion: 1\n${LOGGING_BLOCK}`;
 /** The real dokebi.yaml written by init: same shape, its own header. */
-export const CONFIG_TEMPLATE = '# Settings for this machine. Not committed to Git; dokebi.example.yaml is the shared sample.\nschemaVersion: 1\noptions: {}\n';
+export const CONFIG_TEMPLATE = `# Settings for this machine. Not committed to Git; dokebi.example.yaml is the shared sample.\nschemaVersion: 1\n${LOGGING_BLOCK}`;
 /**
  * Serializes a configuration document edited by the CLI. Non-empty mappings and sequences under
  * `options` are written in block style, so schema comments and values stay readable even when the

package/dist/diagnostics.d.ts

@@ -0,0 +1,21 @@
+/**
+ * CLI diagnostics on stderr (D-0047). The CLI has no logger: errors it recovers from are printed
+ * as one line on stderr, and `DOKEBI_LOG_LEVEL=debug` adds debug lines. stdout stays reserved
+ * for command results (and the --json envelope).
+ */
+/**
+ * The full text of a caught value for a log field (D-0047): name, whole message and stack, then
+ * each `cause` the same way. Only credentials in URLs (`//user:password@`) are removed; a text
+ * over 16 KB is cut and marked. A hostile accessor still yields the value's type.
+ */
+export declare function describeError(error: unknown): string;
+/** Errors that mean "the file or folder is not there", which callers treat as absence. */
+export declare function isMissing(error: unknown): boolean;
+export declare function debugEnabled(): boolean;
+/** A debug line when DOKEBI_LOG_LEVEL=debug. Build costly fields only after debugEnabled(). */
+export declare function debug(message: string, fields?: Record<string, unknown>): void;
+/**
+ * Reports an error the CLI recovers from. Repeats of the same code within `intervalMs` are
+ * counted and the count is added to the next line (for polling loops).
+ */
+export declare function reportError(code: string, message: string, error: unknown, intervalMs?: number): void;

package/dist/diagnostics.js

@@ -0,0 +1,87 @@
+/**
+ * CLI diagnostics on stderr (D-0047). The CLI has no logger: errors it recovers from are printed
+ * as one line on stderr, and `DOKEBI_LOG_LEVEL=debug` adds debug lines. stdout stays reserved
+ * for command results (and the --json envelope).
+ */
+const reported = new Map();
+const suppressed = new Map();
+/**
+ * The full text of a caught value for a log field (D-0047): name, whole message and stack, then
+ * each `cause` the same way. Only credentials in URLs (`//user:password@`) are removed; a text
+ * over 16 KB is cut and marked. A hostile accessor still yields the value's type.
+ */
+export function describeError(error) {
+    const parts = [];
+    let current = error;
+    for (let depth = 0; current !== undefined && depth < 5; depth++) {
+        let text;
+        try {
+            if (current instanceof Error)
+                text = current.stack ?? `${current.name}: ${current.message}`;
+            else if (typeof current === 'string')
+                text = current;
+            else
+                text = `NonError: ${JSON.stringify(current) ?? String(current)}`;
+        }
+        catch {
+            text = `NonError: [${typeof current}]`; // a hostile accessor or a value JSON cannot hold
+        }
+        parts.push(depth ? `Caused by: ${text}` : text);
+        try {
+            current = current instanceof Error ? current.cause : undefined;
+        }
+        catch {
+            current = undefined;
+        }
+    }
+    const text = parts.join('\n').replace(/\/\/[^\s/@]*@/g, '//***@');
+    return text.length > 16_384
+        ? `${text.slice(0, 16_384)}… [truncated ${text.length - 16_384} characters]`
+        : text;
+}
+/** Errors that mean "the file or folder is not there", which callers treat as absence. */
+export function isMissing(error) {
+    const code = error?.code;
+    return code === 'ENOENT' || code === 'ENOTDIR';
+}
+function write(record) {
+    try {
+        process.stderr.write(`${JSON.stringify({ time: new Date().toISOString(), ...record })}\n`);
+    }
+    catch {
+        // stderr itself is unavailable: there is no further channel to report on.
+    }
+}
+export function debugEnabled() {
+    return process.env.DOKEBI_LOG_LEVEL?.trim().toLowerCase() === 'debug';
+}
+/** A debug line when DOKEBI_LOG_LEVEL=debug. Build costly fields only after debugEnabled(). */
+export function debug(message, fields = {}) {
+    if (debugEnabled())
+        write({ level: 'debug', message, ...fields });
+}
+/**
+ * Reports an error the CLI recovers from. Repeats of the same code within `intervalMs` are
+ * counted and the count is added to the next line (for polling loops).
+ */
+export function reportError(code, message, error, intervalMs = 0) {
+    const now = Date.now();
+    const key = `${code}\0${message}`;
+    if (intervalMs > 0) {
+        const last = reported.get(key);
+        if (last !== undefined && now - last < intervalMs) {
+            suppressed.set(key, (suppressed.get(key) ?? 0) + 1);
+            return;
+        }
+    }
+    reported.set(key, now);
+    const repeats = suppressed.get(key);
+    suppressed.delete(key);
+    write({
+        level: 'error',
+        message,
+        code,
+        error: describeError(error),
+        ...(repeats ? { repeated: repeats } : {}),
+    });
+}

package/dist/install-module.js

@@ -2,6 +2,7 @@ import { spawn } from 'node:child_process';
 import { realpath } from 'node:fs/promises';
 import { dirname } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { debug, debugEnabled, describeError } from './diagnostics.js';
 export class InstallPlanningError extends Error {
     code;
     constructor(code) {
@@ -64,10 +65,20 @@ export async function runInstallModule(modulePath, phase, context, readRoots = [
             if (size > MAX_BYTES)
                 stop('INSTALL_OUTPUT_LIMIT');
         });
-        child.on('error', () => stop('INSTALL_PROCESS_FAILED'));
-        child.stdin.on('error', () => stop('INSTALL_INPUT_FAILED'));
+        // Both become the typed InstallPlanningError the caller receives; debug keeps the cause.
+        child.on('error', (error) => {
+            if (debugEnabled())
+                debug('Install module process failed', { phase, error: describeError(error) });
+            stop('INSTALL_PROCESS_FAILED');
+        });
+        child.stdin.on('error', (error) => {
+            if (debugEnabled())
+                debug('Install module input failed', { phase, error: describeError(error) });
+            stop('INSTALL_INPUT_FAILED');
+        });
         child.on('close', (code) => {
             clearTimeout(timer);
+            debug('Install module finished', { phase, exitCode: code, failure: failure?.code });
             if (failure) {
                 reject(failure);
                 return;

package/dist/log-writer.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/log-writer.js

@@ -0,0 +1,133 @@
+// The log writer of `dokebi start` (D-0053). It runs detached from the CLI, starts the app with
+// its stdout and stderr on pipes, and writes whole lines to `.dokebi/run/app.log`, rotating it by
+// size. Reading the pipes means a slow disk slows the app's writes (back pressure) instead of
+// losing lines. It ignores SIGTERM/SIGINT/SIGHUP (dokebi stop signals the app, not the writer)
+// and exits once the app has exited and its pipes are drained.
+//
+// Usage: log-writer <log file> <max bytes> <rotated files to keep> <entry>
+// The CLI listens on the IPC channel until the start is decided: { spawned: pid }, { ready: true }
+// when the start line passes, { exited: code, signal } and { failed: text }. The writer's own
+// errors go to its stderr, which the CLI points at `.dokebi/run/log-writer.log`.
+import { spawn } from 'node:child_process';
+import { debug, describeError, reportError } from './diagnostics.js';
+import { LineBuffer, RotatingLog } from './rotating-log.js';
+/** Written by the generated `src/main.ts` once `app.start()` resolved. */
+const STARTED = 'Dokebi application started';
+/** How long the pipes may stay open after the app exited (a child it left holds them). */
+const DRAIN_MS = 3000;
+/** An unfinished line is written after this much quiet. */
+const PARTIAL_MS = 200;
+function send(message, then) {
+    if (!process.connected) {
+        then?.();
+        return;
+    }
+    process.send?.(message, undefined, {}, (error) => {
+        // The CLI went away between the check and the send: it no longer needs the message.
+        if (error)
+            debug('IPC message not delivered', { error: describeError(error) });
+        then?.();
+    });
+}
+const [file, maxArg, keepArg, entry] = process.argv.slice(2);
+const maxBytes = Number(maxArg);
+const keep = Number(keepArg);
+if (!file ||
+    !entry ||
+    !Number.isSafeInteger(maxBytes) ||
+    maxBytes < 1 ||
+    !Number.isSafeInteger(keep) ||
+    keep < 1) {
+    const text = `usage: log-writer <log file> <max bytes> <files> <entry> (got ${JSON.stringify(process.argv.slice(2))})`;
+    reportError('LOG_WRITER_USAGE', 'Invalid log writer arguments', new Error(text));
+    send({ failed: text }, () => process.exit(2));
+}
+else
+    run(file, maxBytes, keep, entry);
+function run(file, maxBytes, keep, entry) {
+    for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP'])
+        process.on(signal, () => debug('Log writer ignores the signal; it exits when the app exits', { signal }));
+    const log = new RotatingLog(file, maxBytes, keep);
+    try {
+        log.open();
+    }
+    catch (error) {
+        reportError('LOG_OPEN_FAILED', 'Unable to open the app log', error);
+        send({ failed: describeError(error) }, () => process.exit(1));
+        return;
+    }
+    log.write(Buffer.from(`\n--- dokebi start ${new Date().toISOString()} ---\n`));
+    const app = spawn(process.execPath, [entry], { stdio: ['ignore', 'pipe', 'pipe'] });
+    let ready = false;
+    let exit;
+    let open = 2;
+    let finished = false;
+    let drainExpired = false;
+    const finish = () => {
+        if (finished || !exit || (open > 0 && !drainExpired))
+            return;
+        finished = true;
+        const how = exit.signal ? `signal ${exit.signal}` : `code ${exit.code}`;
+        log.write(Buffer.from(`--- dokebi: app exited (${how}) ---\n`));
+        log.close();
+        debug('Log writer finished', { pid: app.pid, code: exit.code, signal: exit.signal });
+        send({ exited: exit.code, signal: exit.signal }, () => process.exit(0));
+    };
+    app.once('error', (error) => {
+        // spawn failed (the app never ran): there is no exit event to wait for.
+        reportError('APP_SPAWN_FAILED', 'Unable to start the app process', error);
+        log.write(Buffer.from(`--- dokebi: app could not start: ${error.message} ---\n`));
+        log.close();
+        send({ failed: describeError(error) }, () => process.exit(1));
+    });
+    if (app.pid !== undefined) {
+        debug('App process spawned by the log writer', { pid: app.pid, maxBytes, keep });
+        send({ spawned: app.pid });
+    }
+    app.once('exit', (code, signal) => {
+        exit = { code, signal };
+        debug('App process exited; draining its output', { pid: app.pid, code, signal });
+        setTimeout(() => {
+            if (finished)
+                return;
+            drainExpired = true;
+            // A process the app started still holds the pipes; stop reading so the writer can end.
+            debug('App output still open after the app exited; closing it', { drainMs: DRAIN_MS });
+            app.stdout?.destroy();
+            app.stderr?.destroy();
+            finish();
+        }, DRAIN_MS).unref();
+        finish();
+    });
+    const follow = (stream, name) => {
+        if (!stream)
+            return;
+        const lines = new LineBuffer();
+        let timer;
+        const write = (data) => {
+            if (!ready && data.includes(STARTED)) {
+                ready = true;
+                send({ ready: true });
+            }
+            log.write(data);
+        };
+        stream.on('data', (chunk) => {
+            const whole = lines.push(chunk);
+            if (whole)
+                write(whole);
+            clearTimeout(timer);
+            if (lines.pending)
+                timer = setTimeout(() => write(lines.take()), PARTIAL_MS);
+        });
+        stream.once('error', (error) => reportError('APP_OUTPUT_FAILED', `Unable to read the app ${name}`, error));
+        stream.once('close', () => {
+            clearTimeout(timer);
+            if (lines.pending)
+                write(lines.take());
+            open--;
+            finish();
+        });
+    };
+    follow(app.stdout, 'stdout');
+    follow(app.stderr, 'stderr');
+}

package/dist/logging-config.d.ts

@@ -0,0 +1,14 @@
+/** Levels accepted by core for `options.logging` (D-0047). */
+export declare const LOG_LEVELS: readonly ['debug', 'info', 'warn', 'error', 'silent'];
+export interface LoggingDiagnostic {
+    code: 'INVALID_LOGGING_CONFIG' | 'LOGGING_PLUGIN_UNKNOWN';
+    path: string;
+    plugin: string | null;
+    severity: 'error' | 'warning';
+    hint?: string;
+}
+/**
+ * Checks `options.logging` the way core does at startup (an invalid value is an error there),
+ * and warns about per-plugin levels for plugins this project does not have.
+ */
+export declare function loggingDiagnostics(options: Record<string, unknown>, plugins: ReadonlySet<string>): LoggingDiagnostic[];

package/dist/logging-config.js

@@ -0,0 +1,48 @@
+import { CONFIG_FILE } from './configuration.js';
+/** Levels accepted by core for `options.logging` (D-0047). */
+export const LOG_LEVELS = ['debug', 'info', 'warn', 'error', 'silent'];
+const isLevel = (value) => typeof value === 'string' && LOG_LEVELS.includes(value);
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * Checks `options.logging` the way core does at startup (an invalid value is an error there),
+ * and warns about per-plugin levels for plugins this project does not have.
+ */
+export function loggingDiagnostics(options, plugins) {
+    const value = options.logging;
+    if (value === undefined || value === null)
+        return [];
+    const base = `${CONFIG_FILE}#options.logging`;
+    const invalid = (path) => ({
+        code: 'INVALID_LOGGING_CONFIG',
+        path,
+        plugin: null,
+        severity: 'error',
+        hint: `use one of: ${LOG_LEVELS.join(', ')}`,
+    });
+    if (!isObject(value) || Object.keys(value).some((key) => key !== 'level' && key !== 'plugins'))
+        return [{ ...invalid(base), hint: 'logging takes only level and plugins' }];
+    const result = [];
+    if (value.level !== undefined && !isLevel(value.level))
+        result.push(invalid(`${base}.level`));
+    if (value.plugins === undefined || value.plugins === null)
+        return result;
+    if (!isObject(value.plugins))
+        return [
+            ...result,
+            { ...invalid(`${base}.plugins`), hint: 'plugins maps plugin names to levels' },
+        ];
+    for (const [name, level] of Object.entries(value.plugins)) {
+        const path = `${base}.plugins.${name}`;
+        if (!isLevel(level))
+            result.push({ ...invalid(path), plugin: name });
+        else if (!plugins.has(name))
+            result.push({
+                code: 'LOGGING_PLUGIN_UNKNOWN',
+                path,
+                plugin: name,
+                severity: 'warning',
+                hint: 'remove the entry or install the plugin',
+            });
+    }
+    return result;
+}

package/dist/npm-client.js

@@ -1,6 +1,7 @@
 import { spawn } from 'node:child_process';
 import { readdir, readFile, writeFile } from 'node:fs/promises';
 import { isAbsolute, resolve } from 'node:path';
+import { debug } from './diagnostics.js';
 import { CliError } from './errors.js';
 import { json, object, parseObject } from './filesystem.js';
 import { PACKAGE_NAME } from './manifest.js';
@@ -77,6 +78,8 @@ export class NpmClient {
         const npmScript = process.env.npm_execpath;
         const command = npmScript?.endsWith('npm-cli.js') ? process.execPath : 'npm';
         const args = [...(npmScript?.endsWith('npm-cli.js') ? [npmScript] : []), ...npmArgs];
+        const began = performance.now();
+        debug('Running npm', { args: npmArgs.slice(0, 16), directory });
         await new Promise((resolvePromise, reject) => {
             const child = spawn(command, args, {
                 cwd: directory,
@@ -93,6 +96,12 @@ export class NpmClient {
             });
             child.on('close', (code) => {
                 clearTimeout(timer);
+                debug('npm finished', {
+                    command: npmArgs[0],
+                    exitCode: code,
+                    timedOut,
+                    ms: Math.round(performance.now() - began),
+                });
                 if (code === 0 && !timedOut)
                     resolvePromise();
                 else

package/dist/output.d.ts

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