@dokebi/cli 0.2.2 → 0.2.4

package/AI.md

@@ -1,9 +1,9 @@
-# AI 작업 안내 — @dokebi/cli 0.2.2 (`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)다.
 
 - Node.js >=24.0.0. 프로젝트 루트에서 그 프로젝트에 설치된 CLI(`npx dokebi`)를 쓴다. 먼저 `npx dokebi --version --json`으로 판을 확인한다.
-- config·core·CLI는 같은 판으로 움직인다(0.2.2). 플러그인은 각자 판이다.
+- CLI·core·config·플러그인은 각자 판이다(D-0046). CLI는 core·config를 `^0.2.2` 범위로 쓰고, `init`은 그 범위의 최신 core를 설치한다.
 
 ## 1. 명령
 
@@ -18,6 +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면 감시 빌드 + 재시작. 띄운 앱에 `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`(계획만)이 있다.
 
@@ -30,6 +32,18 @@
 5. 결과의 `configRequired`(채워야 할 필수 값), `nextSteps`(예: `npm run build`), `warnings`를 처리한다.
 6. `npx dokebi doctor --json`과 앱 테스트·`npm start`로 확인한다.
 
+## 2.1 서버 실행(D-0044, 다음 판)
+
+- 한 프로젝트 = 프로세스 하나(`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)줄(모자라면 `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 출력
 
 stdout에 문서 하나: `{ schemaVersion, cliVersion, command, ok, result?, error? }`. 실패는 종료 1.
@@ -70,8 +84,14 @@ 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`.
-- 진단(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`.
+- 명령: `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`, `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. 주의 사항
@@ -86,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-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.2이다. 명령은 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다.
 
 ## 프로젝트와 명령
 
@@ -12,6 +12,8 @@ Dokebi 프로젝트 생성과 플러그인 설치 도구 0.2.2이다. 명령은
 - dokebi module add|remove|list: `src/shared/modules/<모듈>` 기능 모듈(@dokebi/module).
 - dokebi migrate [--dry-run] [--json]: 기존 JSON 프로젝트를 YAML 계약으로 명시적으로 이전한다.
 - dokebi inspect --json, dokebi doctor --json: 설치 버전·매니페스트·스키마·설정 문제를 읽기 전용으로 확인한다.
+- dokebi dev: 코드·설정이 바뀌면 다시 띄우는 개발 실행(Vite 설정이 있으면 `vite build --watch` 함께).
+- 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

@@ -4,7 +4,8 @@ import { CliError } from './errors.js';
 import { CLI_VERSION, envelope, failure } from './output.js';
 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> [--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]\n';
+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>] [--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');
@@ -72,6 +73,10 @@ async function main() {
         await app(args);
         return;
     }
+    if (['dev', 'start', 'stop', 'status', 'logs'].includes(command)) {
+        await serverCommand(args);
+        return;
+    }
     if (command === 'module') {
         await moduleCommand(args);
         return;
@@ -111,6 +116,107 @@ 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.
+ * `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 (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
+            throw new CliError('USAGE', HELP);
+    }
+    return result;
+}
+/** `dokebi dev|start|stop|status|logs` (D-0044): the project's process. */
+async function serverCommand(input) {
+    const root = process.cwd();
+    const print = (result, text) => process.stdout.write(machine ? JSON.stringify(envelope(command, result)) + '\n' : text + '\n');
+    if (command === 'dev') {
+        if (input.length || machine)
+            throw new CliError('USAGE', HELP);
+        process.exitCode = await server.dev(root, (line) => process.stderr.write(`[dokebi dev] ${line}\n`));
+    }
+    else if (command === 'start') {
+        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')) {
+            // 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 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} (rotated at ${Math.round(result.logMaxBytes / 1048576)} MB, ${result.logFiles} older files kept)`);
+    }
+    else if (command === 'stop') {
+        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
+                ? `not running (pid ${result.pid} had already exited; removed the pid file)`
+                : 'not running');
+    }
+    else if (command === 'status') {
+        if (input.length)
+            throw new CliError('USAGE', HELP);
+        const result = await server.status(root);
+        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`
+                : 'stopped') +
+            (files ? `\nlogs:${files}` : '') +
+            diagnostics);
+        if (!result.running)
+            process.exitCode = 3;
+    }
+    else {
+        if (machine)
+            throw new CliError('USAGE', HELP);
+        const options = serverFlags(input, { '-n': undefined }, ['-f', '--follow']);
+        await server.logs(root, options.numbers.get('-n'), options.switches.has('-f') || options.switches.has('--follow'));
+    }
+}
 /** `dokebi app add|remove|list` (D-0030): apps of @dokebi/app and their domains. */
 async function app(input) {
     const action = input.shift();
@@ -250,6 +356,9 @@ function nextSteps(error) {
         for (const item of details.errors)
             if (typeof item?.missingProperty === 'string')
                 lines.add(`missing: options.${String(details.plugin)}${String(item.instancePath ?? '').replaceAll('/', '.')}.${item.missingProperty}`);
+    const tail = error.details.tail;
+    if (typeof tail === 'string' && tail)
+        lines.add(`last log lines:\n${tail.trimEnd()}`);
     if (error.code === 'WORKSPACE_SYNC_FAILED')
         lines.add('hint: run npm install at the workspace root');
     if (Array.isArray(details.diagnostics))

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/dev-guard.d.ts

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

package/dist/dev-guard.js

@@ -0,0 +1,9 @@
+// Preloaded (`node --import`) into the processes `dokebi dev` starts (D-0044). They get an IPC
+// channel to dev; when dev dies, even by SIGKILL, the channel closes and the process drains
+// (SIGTERM) instead of living on as an orphan that holds the port or keeps building.
+if (process.send) {
+    process.once('disconnect', () => process.kill(process.pid, 'SIGTERM'));
+    // The channel must not keep a finished process alive.
+    process.channel?.unref();
+}
+export {};

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;
+}