@dokebi/cli 0.2.2 → 0.2.3

package/AI.md

@@ -1,9 +1,9 @@
-# AI 작업 안내 — @dokebi/cli 0.2.2 (`dokebi`)
+# AI 작업 안내 — @dokebi/cli 0.2.3 (`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면 감시 빌드 + 재시작(다음 판, D-0044) |
+| `dokebi start [--foreground] [--wait-ms <ms>]` · `stop [--timeout-ms <ms>] [--force]` · `status` · `logs [-n <줄>] [-f]` | 백그라운드 실행·종료·상태·로그(아래 §2.1, 다음 판, D-0044) |
 
 모든 명령에 `--json`(기계용 단일 문서)과 변경 명령에 `--dry-run`(계획만)이 있다.
 
@@ -30,6 +32,17 @@
 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`, 안의 `.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`로 알리고 파일을 지운다.
+- 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`.
+- `src/main.ts`를 고쳐 시작 줄을 지우면 start가 준비 여부를 알 수 없다. 남겨 둔다.
+
 ## 3. JSON 출력
 
 stdout에 문서 하나: `{ schemaVersion, cliVersion, command, ok, result?, error? }`. 실패는 종료 1.
@@ -70,7 +83,7 @@ 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`.
+- 명령: `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`.
 - 경고: `BUILD_SCRIPT_KEPT`, `INERTIA_PLUGIN_MISSING`, `SECRET_ON_COMMAND_LINE`, `EXAMPLE_MISSING`, `EXAMPLE_INVALID`.
 
@@ -86,4 +99,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(서버 명령).

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.3이다. 명령은 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] · 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), 다음 판).
 
 생성 앱의 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>] [--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,75 @@ 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. */
+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);
+            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 options = serverFlags(input, ['--wait-ms'], ['--foreground']);
+        if (options.switches.has('--foreground')) {
+            if (machine)
+                throw new CliError('USAGE', HELP);
+            process.exitCode = await server.foreground(root);
+            return;
+        }
+        const result = await server.start(root, options.numbers.get('--wait-ms'));
+        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}`);
+    }
+    else if (command === 'stop') {
+        const options = serverFlags(input, ['--timeout-ms'], ['--force']);
+        const result = await server.stop(root, options.numbers.get('--timeout-ms'), options.switches.has('--force'));
+        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);
+        print(result, result.running
+            ? `running pid ${result.pid} · up ${result.uptimeSec} s · ${result.rssMb} MB\nlog: ${result.log}`
+            : result.stale
+                ? `stopped: pid ${result.pid} exited without dokebi stop (crashed or killed); see dokebi logs\nlog: ${result.log}`
+                : 'stopped');
+        if (!result.running)
+            process.exitCode = 3;
+    }
+    else {
+        if (machine)
+            throw new CliError('USAGE', HELP);
+        const options = serverFlags(input, ['-n'], ['-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 +324,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/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/output.d.ts

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

package/dist/output.js

@@ -1,5 +1,5 @@
 import { CliError } from './errors.js';
-export const CLI_VERSION = '0.2.2';
+export const CLI_VERSION = '0.2.3';
 export function envelope(command, result, ok = true) {
     return { schemaVersion: 1, cliVersion: CLI_VERSION, command, ok, result, error: null };
 }

package/dist/project.js

@@ -31,7 +31,7 @@ export class Project {
     constructor(npm = new NpmClient()) {
         this.npm = npm;
     }
-    async init(target, core = '@dokebi/core@0.2.2') {
+    async init(target, core = '@dokebi/core@^0.2.2') {
         target = resolve(target);
         if (await exists(target))
             throw new CliError('PROJECT_EXISTS', target);

package/dist/server.d.ts

@@ -0,0 +1,47 @@
+export interface PidRecord {
+    readonly pid: number;
+    readonly startedAt: string;
+    readonly entry: string;
+    readonly node: string;
+}
+export interface ServerStatus {
+    readonly running: boolean;
+    readonly pid?: number;
+    readonly startedAt?: string;
+    readonly uptimeSec?: number;
+    readonly rssMb?: number;
+    /** A pid file was left by a process that is gone (crashed or killed); it was removed. */
+    readonly stale?: boolean;
+    readonly log: string;
+}
+export declare function status(root: string): Promise<ServerStatus>;
+export interface StartResult {
+    readonly pid: number;
+    readonly log: string;
+    /** False when the process is alive but never logged the start line within the wait. */
+    readonly ready: boolean;
+    readonly ms: number;
+    readonly warnings: string[];
+}
+export declare function start(root: string, waitMs?: number, 
+/** Tests replace the project inspection; the CLI always inspects. */
+check?: (root: string) => Promise<string>): Promise<StartResult>;
+export interface StopResult {
+    readonly stopped: boolean;
+    readonly pid?: number;
+    readonly ms?: number;
+    readonly forced?: boolean;
+    readonly stale?: boolean;
+}
+export declare function stop(root: string, timeoutMs?: number, force?: boolean): Promise<StopResult>;
+/** Prints the last `lines` lines; with `follow`, keeps printing what is appended until SIGINT. */
+export declare function logs(root: string, lines?: number, follow?: boolean, write?: (text: string) => void): Promise<void>;
+/** Runs the app in the foreground and forwards SIGINT/SIGTERM; resolves with its exit code. */
+export declare function foreground(root: string): Promise<number>;
+/**
+ * Development loop: runs the app, restarts it (SIGTERM, drain, start) 300 ms after a change in
+ * src/, dokebi.yaml or .env. With a Vite config, Inertia views come from the Vite dev server
+ * inside the app (HMR, D-0045) when template-inertia supports it, otherwise from watch builds
+ * that restart the app. The first Ctrl+C drains everything; a second one kills.
+ */
+export declare function dev(root: string, say: (line: string) => void): Promise<number>;

package/dist/server.js

@@ -0,0 +1,497 @@
+// Server commands (D-0044): dev, start, stop, status and logs for the project's one process
+// (`src/main.ts`). The background process is tracked by `.dokebi/run/app.pid`; its stdout and
+// stderr go to `.dokebi/run/app.log`. A pid is only acted on when `ps` (/proc on Linux) shows it runs this
+// project's entry and started when the pid file says, so a reused pid is never signalled.
+import { execFile, spawn } from 'node:child_process';
+import { existsSync, readFileSync, watch } from 'node:fs';
+import { mkdir, open, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import { CliError } from './errors.js';
+import { ProjectInspector } from './project-inspector.js';
+const exec = promisify(execFile);
+const ENTRY = 'src/main.ts';
+const RUN = '.dokebi/run';
+/** Written by the generated `src/main.ts` once `app.start()` resolved. */
+const STARTED = 'Dokebi application started';
+const LOG_WARN_BYTES = 100 * 1024 * 1024;
+const paths = (root) => ({
+    run: join(root, RUN),
+    pid: join(root, RUN, 'app.pid'),
+    log: join(root, RUN, 'app.log'),
+    lock: join(root, RUN, 'start.lock'),
+    entry: join(root, ENTRY),
+});
+function daemonOnly() {
+    if (process.platform === 'win32')
+        throw new CliError('UNSUPPORTED_PLATFORM', 'Background start and stop need POSIX signals; on Windows use dokebi dev or dokebi start --foreground');
+}
+async function readRecord(root) {
+    let text;
+    try {
+        text = await readFile(paths(root).pid, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const value = JSON.parse(text);
+        if (Number.isSafeInteger(value.pid) && value.pid > 0 && typeof value.entry === 'string')
+            return value;
+    }
+    catch { }
+    return undefined;
+}
+/**
+ * Linux reads /proc: slim container images (node:*-slim) have no `ps`. Start time is the boot
+ * time plus the process start in clock ticks (USER_HZ, 100 on Linux).
+ */
+async function procInfo(pid) {
+    try {
+        const [cmdline, stat, status, uptime] = await Promise.all([
+            readFile(`/proc/${pid}/cmdline`, 'utf8'),
+            readFile(`/proc/${pid}/stat`, 'utf8'),
+            readFile(`/proc/${pid}/status`, 'utf8'),
+            readFile('/proc/stat', 'utf8'),
+        ]);
+        // Fields after the parenthesised command name: state is field 3, starttime field 22.
+        const fields = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+        const ticks = Number(fields[19]);
+        const boot = Number(/^btime (\d+)$/m.exec(uptime)?.[1]);
+        if (!Number.isFinite(ticks) || !Number.isFinite(boot))
+            return undefined;
+        return {
+            startedAt: (boot + ticks / 100) * 1000,
+            rssKb: Number(/^VmRSS:\s+(\d+)/m.exec(status)?.[1] ?? 0),
+            command: cmdline.split('\0').join(' ').trim(),
+        };
+    }
+    catch {
+        return undefined; // no such process
+    }
+}
+async function processInfo(pid) {
+    if (process.platform === 'linux')
+        return procInfo(pid);
+    try {
+        const { stdout } = await exec('ps', ['-ww', '-o', 'lstart=,rss=,command=', '-p', String(pid)], {
+            env: { ...process.env, LC_ALL: 'C' },
+        });
+        // lstart is a fixed 24-character date: "Thu Oct 15 00:21:26 2026".
+        const line = stdout.trim();
+        const startedAt = Date.parse(line.slice(0, 24));
+        const [rss = '', ...command] = line.slice(24).trim().split(/\s+/);
+        if (!Number.isFinite(startedAt))
+            return undefined;
+        return { startedAt, rssKb: Number(rss), command: command.join(' ') };
+    }
+    catch {
+        return undefined; // ps exits 1 when the pid does not exist
+    }
+}
+/** The recorded process, when it is still alive and still this project's process. */
+async function live(record) {
+    const info = await processInfo(record.pid);
+    if (!info?.command.includes(record.entry))
+        return undefined;
+    // lstart has one-second resolution; the pid file is written right after spawn.
+    if (Math.abs(info.startedAt - Date.parse(record.startedAt)) > 5000)
+        return undefined;
+    return info;
+}
+export async function status(root) {
+    const { pid, log } = paths(root);
+    const record = await readRecord(root);
+    if (!record)
+        return { running: false, log };
+    const info = await live(record);
+    if (!info) {
+        await rm(pid, { force: true });
+        return { running: false, stale: true, pid: record.pid, startedAt: record.startedAt, log };
+    }
+    return {
+        running: true,
+        pid: record.pid,
+        startedAt: record.startedAt,
+        uptimeSec: Math.round((Date.now() - Date.parse(record.startedAt)) / 1000),
+        rssMb: Math.round(info.rssKb / 1024),
+        log,
+    };
+}
+async function checkProject(root) {
+    const { entry } = paths(root);
+    if (!existsSync(entry))
+        throw new CliError('ENTRY_MISSING', `${ENTRY} does not exist`);
+    const inspection = await new ProjectInspector().inspect(root);
+    if (!inspection.healthy)
+        throw new CliError('START_CHECK_FAILED', 'The project has errors; run dokebi doctor', {
+            details: {
+                diagnostics: inspection.diagnostics.filter((item) => item.severity === 'error'),
+            },
+        });
+    return entry;
+}
+const environment = (mode) => ({
+    ...process.env,
+    NODE_ENV: process.env.NODE_ENV ?? mode,
+});
+async function tail(file, lines, maxBytes = 1024 * 1024) {
+    let handle;
+    try {
+        handle = await open(file, 'r');
+        const { size } = await handle.stat();
+        const length = Math.min(size, maxBytes);
+        const buffer = Buffer.alloc(length);
+        await handle.read(buffer, 0, length, size - length);
+        const text = buffer.toString('utf8').split('\n');
+        if (text.at(-1) === '')
+            text.pop();
+        return text.slice(-lines).join('\n') + (text.length ? '\n' : '');
+    }
+    catch {
+        return '';
+    }
+    finally {
+        await handle?.close();
+    }
+}
+export async function start(root, waitMs = 10_000, 
+/** Tests replace the project inspection; the CLI always inspects. */
+check = checkProject) {
+    daemonOnly();
+    const files = paths(root);
+    const began = performance.now();
+    const current = await status(root);
+    if (current.running)
+        throw new CliError('ALREADY_RUNNING', `Already running (pid ${current.pid})`, {
+            details: current,
+        });
+    const entry = await check(root);
+    await mkdir(files.run, { recursive: true });
+    await writeFile(join(files.run, '.gitignore'), '*\n');
+    // One start at a time; a lock left by a start that died more than a minute ago is stale.
+    try {
+        await writeFile(files.lock, String(process.pid), { flag: 'wx' });
+    }
+    catch {
+        const age = Date.now() - (await stat(files.lock).catch(() => ({ mtimeMs: 0 }))).mtimeMs;
+        if (age < 60_000)
+            throw new CliError('START_IN_PROGRESS', 'Another dokebi start is running for this project');
+        await writeFile(files.lock, String(process.pid));
+    }
+    const warnings = [];
+    try {
+        const before = await stat(files.log).catch(() => undefined);
+        if (before && before.size > LOG_WARN_BYTES)
+            warnings.push(`${RUN}/app.log is ${Math.round(before.size / 1048576)} MB; it is not rotated`);
+        const offset = before?.size ?? 0;
+        const log = await open(files.log, 'a');
+        let child;
+        try {
+            await log.write(`\n--- dokebi start ${new Date().toISOString()} ---\n`);
+            child = spawn(process.execPath, [entry], {
+                cwd: root,
+                detached: true,
+                stdio: ['ignore', log.fd, log.fd],
+                env: environment('production'),
+            });
+        }
+        finally {
+            await log.close();
+        }
+        const pid = child.pid;
+        if (pid === undefined)
+            throw new CliError('START_FAILED', 'The process could not be spawned');
+        let exited;
+        child.once('exit', (code, signal) => {
+            exited = code ?? (signal ? 128 : 1);
+        });
+        child.unref();
+        const record = {
+            pid,
+            startedAt: new Date().toISOString(),
+            entry,
+            node: process.version,
+        };
+        await writeFile(`${files.pid}.tmp`, `${JSON.stringify(record)}\n`);
+        await rename(`${files.pid}.tmp`, files.pid);
+        const deadline = performance.now() + waitMs;
+        let ready = false;
+        while (performance.now() < deadline) {
+            await delay(100);
+            if (exited !== undefined) {
+                await rm(files.pid, { force: true });
+                throw new CliError('START_FAILED', `The application exited with code ${exited}`, {
+                    details: { log: files.log, tail: await tail(files.log, 30) },
+                });
+            }
+            const text = await readFile(files.log).catch(() => Buffer.alloc(0));
+            if (text.subarray(offset).includes(STARTED)) {
+                ready = true;
+                break;
+            }
+        }
+        if (!ready)
+            warnings.push(`"${STARTED}" was not logged within ${waitMs} ms; the process is running but may not be ready`);
+        return { pid, log: files.log, ready, ms: Math.round(performance.now() - began), warnings };
+    }
+    finally {
+        await rm(files.lock, { force: true });
+    }
+}
+export async function stop(root, timeoutMs = 30_000, force = false) {
+    daemonOnly();
+    const files = paths(root);
+    const record = await readRecord(root);
+    if (!record)
+        return { stopped: false };
+    if (!(await live(record))) {
+        await rm(files.pid, { force: true });
+        return { stopped: false, pid: record.pid, stale: true };
+    }
+    const began = performance.now();
+    const gone = async (limit) => {
+        const until = performance.now() + limit;
+        while (performance.now() < until) {
+            if (!(await live(record)))
+                return true;
+            await delay(100);
+        }
+        return false;
+    };
+    process.kill(record.pid, 'SIGTERM');
+    let forced = false;
+    if (!(await gone(timeoutMs))) {
+        if (!force)
+            throw new CliError('STOP_TIMEOUT', `pid ${record.pid} did not stop within ${timeoutMs} ms; it is still draining or stuck (use --force)`);
+        process.kill(record.pid, 'SIGKILL');
+        forced = true;
+        if (!(await gone(5000)))
+            throw new CliError('STOP_TIMEOUT', `pid ${record.pid} survived SIGKILL`);
+    }
+    await rm(files.pid, { force: true });
+    return { stopped: true, pid: record.pid, ms: Math.round(performance.now() - began), forced };
+}
+/** Prints the last `lines` lines; with `follow`, keeps printing what is appended until SIGINT. */
+export async function logs(root, lines = 100, follow = false, write = (text) => process.stdout.write(text)) {
+    const file = paths(root).log;
+    if (!follow && !existsSync(file))
+        throw new CliError('NO_LOG', `${RUN}/app.log does not exist; the app was never started`);
+    write(await tail(file, lines));
+    if (!follow)
+        return;
+    let position = (await stat(file).catch(() => ({ size: 0 }))).size;
+    const stopped = new AbortController();
+    process.once('SIGINT', () => stopped.abort());
+    while (!stopped.signal.aborted) {
+        await delay(250);
+        const size = (await stat(file).catch(() => ({ size: 0 }))).size;
+        if (size < position)
+            position = 0; // removed or truncated: follow the new file
+        if (size === position)
+            continue;
+        const handle = await open(file, 'r');
+        try {
+            const buffer = Buffer.alloc(size - position);
+            await handle.read(buffer, 0, buffer.length, position);
+            write(buffer.toString('utf8'));
+            position = size;
+        }
+        finally {
+            await handle.close();
+        }
+    }
+}
+/** Runs the app in the foreground and forwards SIGINT/SIGTERM; resolves with its exit code. */
+export async function foreground(root) {
+    const entry = await checkProject(root);
+    const child = spawn(process.execPath, [entry], {
+        cwd: root,
+        stdio: 'inherit',
+        env: environment('production'),
+    });
+    const forward = (signal) => () => child.kill(signal);
+    const onInt = forward('SIGINT');
+    const onTerm = forward('SIGTERM');
+    process.on('SIGINT', onInt);
+    process.on('SIGTERM', onTerm);
+    try {
+        return await new Promise((resolve) => child.once('exit', (code, signal) => resolve(code ?? (signal ? 128 : 1))));
+    }
+    finally {
+        process.off('SIGINT', onInt);
+        process.off('SIGTERM', onTerm);
+    }
+}
+/** The installed version of a package, looked up like Node does (node_modules up the tree). */
+function installedVersion(root, name) {
+    for (let directory = root;; directory = dirname(directory)) {
+        try {
+            const { version } = JSON.parse(readFileSync(join(directory, 'node_modules', name, 'package.json'), 'utf8'));
+            const parts = /^(\d+)\.(\d+)\.(\d+)/.exec(String(version));
+            return parts ? [Number(parts[1]), Number(parts[2]), Number(parts[3])] : undefined;
+        }
+        catch { }
+        if (dirname(directory) === directory)
+            return undefined;
+    }
+}
+/** template-inertia 0.1.2 serves views from the Vite dev server with HMR (D-0045). */
+function inertiaDevServer(root) {
+    const version = installedVersion(root, '@dokebi/template-inertia');
+    if (!version)
+        return false;
+    const [major, minor, patch] = version;
+    return major > 0 || minor > 1 || (minor === 1 && patch >= 2);
+}
+/** Files the Vite dev server owns: a change reaches the browser by HMR, not by a restart. */
+const VIEW_FILE = /(^|[\\/])views[\\/].*\.(js|mjs|ts)$|\.(vue|css|scss|sass|less)$/;
+/**
+ * Development loop: runs the app, restarts it (SIGTERM, drain, start) 300 ms after a change in
+ * src/, dokebi.yaml or .env. With a Vite config, Inertia views come from the Vite dev server
+ * inside the app (HMR, D-0045) when template-inertia supports it, otherwise from watch builds
+ * that restart the app. The first Ctrl+C drains everything; a second one kills.
+ */
+export async function dev(root, say) {
+    const entry = await checkProject(root);
+    let app;
+    let exiting = false;
+    const hasVite = ['vite.config.ts', 'vite.config.mjs', 'vite.config.js'].some((name) => existsSync(join(root, name)));
+    const hot = hasVite && inertiaDevServer(root);
+    if (hot)
+        say('Inertia views: Vite dev server with hot module replacement');
+    const guard = new URL('./dev-guard.js', import.meta.url).href;
+    // stdio fd 3 is the IPC channel the guard watches.
+    const child = (args) => spawn(process.execPath, ['--import', guard, ...args], {
+        cwd: root,
+        stdio: ['inherit', 'inherit', 'inherit', 'ipc'],
+        env: { ...environment('development'), ...(hot ? { DOKEBI_VITE_DEV: '1' } : {}) },
+    });
+    const run = () => {
+        app = child([entry]);
+        const current = app;
+        current.once('exit', (code, signal) => {
+            if (app === current && !exiting)
+                say(`app exited (${signal ?? code}); waiting for a change to restart`);
+        });
+    };
+    const halt = async (target, limitMs = 15_000) => {
+        if (!target || target.exitCode !== null || target.signalCode !== null)
+            return;
+        const exited = new Promise((resolve) => target.once('exit', resolve));
+        target.kill('SIGTERM');
+        const timer = setTimeout(() => target.kill('SIGKILL'), limitMs);
+        await exited;
+        clearTimeout(timer);
+    };
+    // Vite builds in watch mode beside the app. The app starts after every first build (a build
+    // empties dist/ first, and the SSR bundle is read once at start) and restarts after rebuilds.
+    const helpers = [];
+    const firstBuilds = [];
+    let built = () => { };
+    const vite = join(root, 'node_modules/vite/dist/node/index.js');
+    const watchScript = fileURLToPath(new URL('./vite-watch.js', import.meta.url));
+    for (const [config, label] of [
+        [['vite.config.ts', 'vite.config.mjs', 'vite.config.js'], 'vite'],
+        [['vite.ssr.config.ts', 'vite.ssr.config.mjs', 'vite.ssr.config.js'], 'vite ssr'],
+    ]) {
+        const file = config.find((name) => existsSync(join(root, name)));
+        if (hot || !file || !existsSync(vite))
+            continue;
+        say(`${label}: watching (${file})`);
+        const helper = child([watchScript, file]);
+        helpers.push(helper);
+        let first = true;
+        let resolveFirst;
+        let rejectFirst;
+        firstBuilds.push(new Promise((resolve, reject) => {
+            resolveFirst = resolve;
+            rejectFirst = reject;
+        }));
+        helper.on('message', (message) => {
+            if (message?.failed)
+                say(`${label} build failed; fix it and save again`);
+            if (!message?.built)
+                return;
+            if (first) {
+                first = false;
+                resolveFirst();
+            }
+            else
+                built(label);
+        });
+        helper.once('exit', (code, signal) => {
+            rejectFirst(new CliError('DEV_BUILD_FAILED', `${label} exited (${signal ?? code})`));
+            if (!exiting)
+                say(`${label} exited (${signal ?? code})`);
+        });
+    }
+    if (firstBuilds.length)
+        say('waiting for the first builds');
+    try {
+        await Promise.all(firstBuilds);
+    }
+    catch (error) {
+        exiting = true;
+        await Promise.all(helpers.map((helper) => halt(helper, 5000)));
+        throw error;
+    }
+    run();
+    let timer;
+    let restarting = Promise.resolve();
+    const changed = (what) => {
+        if (exiting)
+            return;
+        clearTimeout(timer);
+        timer = setTimeout(() => {
+            restarting = restarting.then(async () => {
+                if (exiting)
+                    return;
+                say(`${what} changed; restarting`);
+                const previous = app;
+                app = undefined;
+                await halt(previous);
+                if (!exiting)
+                    run();
+            });
+        }, 300);
+    };
+    built = (label) => changed(`${label} build`);
+    const watchers = [
+        watch(join(root, 'src'), { recursive: true }, (_event, name) => {
+            // Styles and components reach the app through the Vite builds (restart after the build).
+            if (hot && name && VIEW_FILE.test(name))
+                return;
+            if (helpers.length && name && /\.(vue|css|scss|sass|less)$/.test(name))
+                return;
+            changed(`src/${name ?? ''}`);
+        }),
+        watch(root, (_event, name) => {
+            if (name === 'dokebi.yaml' || name === '.env')
+                changed(name);
+        }),
+    ];
+    return await new Promise((resolve) => {
+        const finish = async () => {
+            if (exiting) {
+                app?.kill('SIGKILL');
+                for (const helper of helpers)
+                    helper.kill('SIGKILL');
+                resolve(130);
+                return;
+            }
+            exiting = true;
+            say('stopping (Ctrl+C again to kill)');
+            clearTimeout(timer);
+            for (const watcher of watchers)
+                watcher.close();
+            await restarting;
+            await Promise.all([halt(app), ...helpers.map((helper) => halt(helper, 5000))]);
+            resolve(0);
+        };
+        process.on('SIGINT', () => void finish());
+        process.on('SIGTERM', () => void finish());
+    });
+}

package/dist/vite-watch.d.ts

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

package/dist/vite-watch.js

@@ -0,0 +1,23 @@
+// Run by `dokebi dev` (D-0044) for one Vite config: a watch build that never empties its outDir.
+// The browser build's `emptyOutDir: true` would otherwise delete dist/ssr/ on every rebuild,
+// which is fine for `npm run build` (one build after the other) but not for two watchers.
+// Every finished build is reported to dev over the IPC channel ({ built: true } or
+// { failed: true }); output goes to the terminal as usual.
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+const configFile = process.argv[2];
+if (!configFile)
+    throw new Error('usage: vite-watch <config>');
+const vite = (await import(pathToFileURL(join(process.cwd(), 'node_modules/vite/dist/node/index.js')).href));
+const watcher = (await vite.build({
+    configFile,
+    build: { watch: {}, emptyOutDir: false },
+}));
+watcher.on('event', (event) => {
+    if (event.code === 'BUNDLE_END')
+        void event.result?.close();
+    if (event.code === 'END')
+        process.send?.({ built: true });
+    if (event.code === 'ERROR')
+        process.send?.({ failed: true });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dokebi/cli",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "private": false,
   "publishConfig": {
     "access": "public",
@@ -24,8 +24,8 @@
   },
   "dependencies": {
     "semver": "7.8.5",
-    "@dokebi/core": "0.2.2",
-    "@dokebi/config": "0.2.2",
+    "@dokebi/core": "^0.2.2",
+    "@dokebi/config": "^0.2.2",
     "yaml": "2.9.1"
   },
   "devDependencies": {