@ywal123456/jskim 0.1.1 → 0.2.0

package/README.md

@@ -25,13 +25,15 @@ Nunjucks ソースを設定に従って静的 HTML にレンダリングし、as
 
 - ブラウザ自動起動
 - HMR / CSS だけのホット更新
-- HTML 移行
 - JSON データの自動読み込み
 - API / Mock API
-- config の hot reload
 - 増分ビルド
 - SPA fallback / proxy
 
+既存 HTML の自動 import / migration は JSKim core の責任範囲外です。
+既存 source の移行は利用者が project に合わせて行います。
+将来必要になった場合も、JSKim 本体ではなく独立した tool / package として検討します。
+
 ## パッケージの役割
 
 | 名称 | 種類 | 役割 |
@@ -170,9 +172,24 @@ jskim watch sample
 
 - 関連する変更はすべて **全体ビルド** です（増分 render / 単一 asset copy なし）。
 - `build.clean: true` のとき、再ビルドで outputDir を消して作り直すため、ソース削除も結果に反映されます。
-- `jskim.config.js` を変更した場合は **watch / dev を再起動** してください（config hot reload なし）。
+- `jskim.config.js` の変更は **watch / dev が検知** し、正常なら監視対象を更新して全体ビルドします。
+- 設定の読み込み / 検証に失敗しても process は終了せず、以前の正常な設定を継続します。
+- `serve` は config を監視しません。設定変更後は serve process の再起動が必要です。
 - 終了: `Ctrl+C`（SIGINT）または SIGTERM → `[JSKim] ウォッチを停止しました。`
 
+#### config hot reload（watch / dev）
+
+- 対象ファイル: ワークスペースルートの `jskim.config.js`
+- 正常な変更: watcher 再構成 → 全体ビルド
+- 不正な設定: 以前の正常な設定を維持し、修正後に自動で再試行
+- `watch` では `outputDir` 変更も適用できます（以前の outputDir は自動削除しません）
+- `dev` では次の変更は process 再起動が必要です:
+  - `outputDir`
+  - `serve.host`
+  - `serve.port`
+  - `dev.liveReload`
+- `dev` で対応できる設定変更が成功し、build も成功した場合だけ browser reload を 1 回送ります
+
 debounce の既定値は `watch.debounce: 150`（ms）で、プロジェクトごとに上書きできます。詳細は [docs/configuration.md](docs/configuration.md) を参照してください。
 
 ## 静的サーバー（serve）
@@ -237,7 +254,8 @@ http://127.0.0.1:3000/
 
 `dev.liveReload: false` にすると SSE endpoint と script 注入を無効化できます。
 
-設定を変えた場合は `dev` を再起動してください。
+`jskim.config.js` の build / watch 関連設定は hot reload されます。
+`outputDir` / `serve.host` / `serve.port` / `dev.liveReload` を変えた場合は `dev` を再起動してください。
 
 終了: `Ctrl+C` → `[JSKim] 開発サーバーを停止しました。`
 

package/docs/configuration.md

@@ -185,8 +185,9 @@ projects: {
 
 注意:
 
-- この段階では `jskim.config.js` 自体は watch しません
-- 設定を変えた場合は watch コマンドを再起動してください
+- `watch` / `dev` 実行中は `jskim.config.js` 自体も監視します
+- 正常な設定変更は監視対象の再構成と全体ビルドに反映されます
+- 設定の読み込み / 検証エラー時は以前の正常な設定を継続します
 
 ## serve.host
 
@@ -295,7 +296,51 @@ projects: {
 
 `dev.host` / `dev.port` / `dev.debounce` は用意しません。
 
-設定変更後は実行中の watcher/server は自動再構成されないため、`dev` / `watch` / `serve` を再起動してください。
+## config hot reload
+
+`watch` と `dev` はワークスペースルートの `jskim.config.js` を監視します。
+
+### コマンド別
+
+| コマンド | 動作 |
+|----------|------|
+| `build` | 実行時に config を 1 回読み込む。監視しない |
+| `serve` | 実行時に config を 1 回読み込む。監視しない。変更後は process 再起動が必要 |
+| `watch` | config 変更を hot apply。`outputDir` 変更も可。以前の outputDir は自動削除しない |
+| `dev` | build / watch 関連設定を hot apply。一部 runtime 設定は再起動が必要 |
+
+### 正常な reload
+
+1. config 変更を検知
+2. fresh load（CommonJS require cache を `jskim.config.js` について削除）
+3. merge / project resolve / validation
+4. watcher 再構成
+5. 全体ビルド
+
+### エラー時
+
+| 状況 | 動作 |
+|------|------|
+| config load / resolve / validation エラー | 以前の正常な設定を維持。process は終了しない |
+| 新しい設定適用後の build エラー | 新しい設定 / watcher を維持。process は終了しない。修正後に再試行 |
+| config 一時削除（unlink） | 以前の設定を継続。再作成後に reload |
+
+### `dev` で再起動が必要な設定
+
+次の値が変わった candidate config は適用しません。
+
+- `outputDir`
+- `serve.host`
+- `serve.port`
+- `dev.liveReload`
+
+理由: server bind と serve root を安全に切り替えるには process 再起動が必要で、部分適用すると build output と serve root がずれるためです。
+
+### 制限
+
+- config hot reload は常に **全体ビルド** です（増分 build ではありません）
+- `jskim.config.js` が require した別 helper module だけの変更は自動反映しません。config を保存し直すか process を再起動してください
+- `node_modules` や JSKim package 自身の require cache は一括削除しません
 
 ## パス基準のまとめ
 

package/docs/create-jskim.md

@@ -39,12 +39,12 @@ project/
 ```
 
 `package.json` の scripts は bin 名 `jskim` を使います（package name ではありません）。
-既定の engine dependency は `@ywal123456/jskim`（`^0.1.0`）です。
+既定の engine dependency は `@ywal123456/jskim`（`^0.2.0`）です。
 
 ```json
 {
   "devDependencies": {
-    "@ywal123456/jskim": "^0.1.0"
+    "@ywal123456/jskim": "^0.2.0"
   },
   "scripts": {
     "build": "jskim build sample",
@@ -70,7 +70,7 @@ create package の `package.json` に `jskimEngine` metadata を持ち、生成
 {
   "jskimEngine": {
     "packageName": "@ywal123456/jskim",
-    "version": "^0.1.0"
+    "version": "^0.2.0"
   }
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ywal123456/jskim",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Nunjucks-based static HTML build environment with watch, serve, and live reload",
   "keywords": [
     "nunjucks",

package/scripts/commands/dev-command.js

@@ -1,13 +1,7 @@
 'use strict';
 
-const { loadConfig } = require('../lib/load-config');
-const { resolveProject } = require('../lib/resolve-project');
-const { createProjectWatcher } = require('../lib/create-project-watcher');
-const { createStaticServer } = require('../lib/create-static-server');
-const { createLiveReload } = require('../lib/create-live-reload');
+const { createWatchRuntime } = require('../lib/create-watch-runtime');
 const { registerShutdown } = require('./register-shutdown');
-const { toDisplayPath } = require('./path-display');
-const { formatListenError } = require('./serve-errors');
 
 /**
  * dev コマンドを実行します。
@@ -22,51 +16,15 @@ async function runDevCommand(options = {}) {
   const usageLine =
     options.usageLine || 'npm run dev -- <project-name>';
 
-  const { config } = loadConfig(workspaceRoot);
-  const project = resolveProject({
-    config,
+  const runtime = createWatchRuntime({
+    mode: 'dev',
     workspaceRoot,
     projectName: options.projectName,
     commandName: 'dev',
     usageLine,
   });
 
-  const host = project.serve.host.trim();
-  const port = project.serve.port;
-  const liveReloadEnabled = project.dev.liveReload;
-  const outputDisplay = toDisplayPath(project.outputDir, workspaceRoot);
-
-  const liveReload = createLiveReload({
-    projectName: project.name,
-    enabled: liveReloadEnabled,
-  });
-
-  const staticServer = createStaticServer({
-    rootDir: project.outputDir,
-    host,
-    port,
-    projectName: project.name,
-    handleInternalRequest: (req, res, meta) =>
-      liveReload.handleRequest(req, res, meta),
-    transformHtml: liveReloadEnabled
-      ? (html) => liveReload.injectHtml(html)
-      : undefined,
-  });
-
-  const projectWatcher = createProjectWatcher(project, {
-    runInitialBuild: true,
-    logChanges: true,
-  });
-
-  // 成功した再ビルドのあとだけ reload（初回はクライアント未接続のため不要）
-  projectWatcher.on('build:success', ({ initial }) => {
-    if (!initial && liveReloadEnabled) {
-      liveReload.broadcastReload();
-    }
-  });
-
   let stopping = false;
-  let watcherStarted = false;
 
   async function shutdown() {
     if (stopping) {
@@ -75,21 +33,7 @@ async function runDevCommand(options = {}) {
     stopping = true;
 
     try {
-      if (watcherStarted) {
-        await projectWatcher.close();
-      }
-    } catch {
-      // 終了時エラーは無視
-    }
-
-    try {
-      liveReload.close();
-    } catch {
-      // 終了時エラーは無視
-    }
-
-    try {
-      await staticServer.stop();
+      await runtime.close();
     } catch {
       // 終了時エラーは無視
     }
@@ -98,65 +42,22 @@ async function runDevCommand(options = {}) {
     process.exit(0);
   }
 
-  async function failStartup(err) {
+  registerShutdown(shutdown);
+
+  try {
+    await runtime.start();
+  } catch (err) {
     const message = err && err.message ? err.message : String(err);
     console.error(message);
-
-    try {
-      if (watcherStarted) {
-        await projectWatcher.close();
-      }
-    } catch {
-      // ignore
-    }
-
-    try {
-      liveReload.close();
-    } catch {
-      // ignore
-    }
-
     try {
-      await staticServer.stop();
+      await runtime.close();
     } catch {
       // ignore
     }
-
     // cleanup 完了後に終了する。
     // IPC 接続があると exitCode だけではプロセスが残るため明示終了する。
     process.exit(1);
   }
-
-  registerShutdown(shutdown);
-
-  // 初回 build → server → watcher
-  await projectWatcher.start({ watchFiles: false });
-  watcherStarted = true;
-
-  try {
-    await staticServer.start();
-  } catch (err) {
-    await failStartup(
-      formatListenError(err, {
-        projectName: project.name,
-        host,
-        port,
-        kind: '開発',
-      })
-    );
-    return;
-  }
-
-  await projectWatcher.startWatching();
-
-  console.log('[JSKim] 開発サーバーを起動しました。');
-  console.log(`プロジェクト: ${project.name}`);
-  console.log(`ルート: ${outputDisplay}`);
-  console.log(`URL: ${staticServer.url}`);
-  console.log(
-    `ライブリロード: ${liveReloadEnabled ? '有効' : '無効'}`
-  );
-  console.log('終了するには Ctrl+C を押してください。');
 }
 
 module.exports = {

package/scripts/commands/watch-command.js

@@ -1,8 +1,6 @@
 'use strict';
 
-const { loadConfig } = require('../lib/load-config');
-const { resolveProject } = require('../lib/resolve-project');
-const { createProjectWatcher } = require('../lib/create-project-watcher');
+const { createWatchRuntime } = require('../lib/create-watch-runtime');
 const { registerShutdown } = require('./register-shutdown');
 
 /**
@@ -18,33 +16,14 @@ async function runWatchCommand(options = {}) {
   const usageLine =
     options.usageLine || 'npm run watch -- <project-name>';
 
-  const { config } = loadConfig(workspaceRoot);
-  const project = resolveProject({
-    config,
+  const runtime = createWatchRuntime({
+    mode: 'watch',
     workspaceRoot,
     projectName: options.projectName,
     commandName: 'watch',
     usageLine,
   });
 
-  const projectWatcher = createProjectWatcher(project, {
-    runInitialBuild: true,
-    logChanges: true,
-  });
-
-  projectWatcher.on('ready', ({ displayPaths, debounceMs }) => {
-    console.log(`[JSKim] プロジェクトを監視しています: ${project.name}`);
-    console.log('パス:');
-    for (const display of displayPaths) {
-      console.log(`- ${display}`);
-    }
-    console.log('');
-    console.log(`Debounce: ${debounceMs}ms`);
-    console.log('終了するには Ctrl+C を押してください。');
-  });
-
-  await projectWatcher.start();
-
   let stopping = false;
 
   async function shutdown() {
@@ -54,7 +33,7 @@ async function runWatchCommand(options = {}) {
     stopping = true;
 
     try {
-      await projectWatcher.close();
+      await runtime.close();
     } catch {
       // 終了時エラーは無視
     }
@@ -64,6 +43,17 @@ async function runWatchCommand(options = {}) {
   }
 
   registerShutdown(shutdown);
+
+  try {
+    await runtime.start();
+  } catch (err) {
+    try {
+      await runtime.close();
+    } catch {
+      // ignore
+    }
+    throw err;
+  }
 }
 
 module.exports = {

package/scripts/lib/create-watch-runtime.js

@@ -0,0 +1,516 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const chokidar = require('chokidar');
+const { loadConfig, CONFIG_FILENAME } = require('./load-config');
+const { resolveProject } = require('./resolve-project');
+const { createProjectWatcher } = require('./create-project-watcher');
+const { createStaticServer } = require('./create-static-server');
+const { createLiveReload } = require('./create-live-reload');
+const { formatListenError } = require('../commands/serve-errors');
+
+const DEV_RESTART_KEYS = [
+  'outputDir',
+  'serve.host',
+  'serve.port',
+  'dev.liveReload',
+];
+
+/**
+ * watch / dev 共通の実行ランタイムです。
+ * jskim.config.js の hot reload と project watcher 再構成を担当します。
+ *
+ * @param {object} options
+ * @param {'watch'|'dev'} options.mode
+ * @param {string} options.workspaceRoot
+ * @param {string|undefined} options.projectName
+ * @param {string} [options.commandName]
+ * @param {string} [options.usageLine]
+ * @returns {{ start: Function, close: Function }}
+ */
+function createWatchRuntime(options) {
+  const mode = options.mode;
+  const workspaceRoot = options.workspaceRoot || process.cwd();
+  const projectName = options.projectName;
+  const commandName = options.commandName || mode;
+  const usageLine =
+    options.usageLine || `npm run ${commandName} -- <project-name>`;
+
+  let currentProject = null;
+  let configPath = null;
+  let projectWatcher = null;
+  let configWatcher = null;
+  let liveReload = null;
+  let staticServer = null;
+  let liveReloadEnabled = false;
+
+  let stopping = false;
+  let started = false;
+  let configDebounceTimer = null;
+  let configReloadPromise = null;
+  let pendingConfigReload = false;
+  let sourceBuilding = false;
+
+  function resolveCurrentProject() {
+    const loaded = loadConfig(workspaceRoot);
+    const project = resolveProject({
+      config: loaded.config,
+      workspaceRoot,
+      projectName,
+      commandName,
+      usageLine,
+    });
+    return {
+      project,
+      configPath: loaded.configPath,
+    };
+  }
+
+  async function start() {
+    if (started) {
+      return;
+    }
+    started = true;
+
+    const resolved = resolveCurrentProject();
+    currentProject = resolved.project;
+    configPath = resolved.configPath;
+
+    if (mode === 'dev') {
+      await startDevSession(currentProject, { initial: true });
+    } else {
+      await startWatchSession(currentProject, { initial: true });
+    }
+
+    beginConfigWatching();
+  }
+
+  async function startWatchSession(project, { initial }) {
+    projectWatcher = createProjectWatcher(project, {
+      runInitialBuild: true,
+      logChanges: true,
+    });
+
+    wireSourceBuildTracking(projectWatcher);
+
+    if (initial) {
+      projectWatcher.on('ready', ({ displayPaths, debounceMs }) => {
+        console.log(`[JSKim] プロジェクトを監視しています: ${project.name}`);
+        console.log('パス:');
+        for (const display of displayPaths) {
+          console.log(`- ${display}`);
+        }
+        console.log('');
+        console.log(`Debounce: ${debounceMs}ms`);
+        console.log('終了するには Ctrl+C を押してください。');
+      });
+    }
+
+    await projectWatcher.start();
+  }
+
+  async function startDevSession(project, { initial }) {
+    liveReloadEnabled = project.dev.liveReload;
+    const host = project.serve.host.trim();
+    const port = project.serve.port;
+    const outputDisplay = toDisplayPath(project.outputDir, workspaceRoot);
+
+    liveReload = createLiveReload({
+      projectName: project.name,
+      enabled: liveReloadEnabled,
+    });
+
+    staticServer = createStaticServer({
+      rootDir: project.outputDir,
+      host,
+      port,
+      projectName: project.name,
+      handleInternalRequest: (req, res, meta) =>
+        liveReload.handleRequest(req, res, meta),
+      transformHtml: liveReloadEnabled
+        ? (html) => liveReload.injectHtml(html)
+        : undefined,
+    });
+
+    projectWatcher = createProjectWatcher(project, {
+      runInitialBuild: true,
+      logChanges: true,
+    });
+
+    wireSourceBuildTracking(projectWatcher);
+    wireDevSourceReload(projectWatcher);
+
+    await projectWatcher.start({ watchFiles: false });
+
+    try {
+      await staticServer.start();
+    } catch (err) {
+      const formatted = formatListenError(err, {
+        projectName: project.name,
+        host,
+        port,
+        kind: '開発',
+      });
+      await cleanupDevComponents();
+      throw formatted;
+    }
+
+    await projectWatcher.startWatching();
+
+    if (initial) {
+      console.log('[JSKim] 開発サーバーを起動しました。');
+      console.log(`プロジェクト: ${project.name}`);
+      console.log(`ルート: ${outputDisplay}`);
+      console.log(`URL: ${staticServer.url}`);
+      console.log(
+        `ライブリロード: ${liveReloadEnabled ? '有効' : '無効'}`
+      );
+      console.log('終了するには Ctrl+C を押してください。');
+    }
+  }
+
+  function wireSourceBuildTracking(watcher) {
+    watcher.on('build:start', () => {
+      sourceBuilding = true;
+    });
+    watcher.on('build:success', () => {
+      sourceBuilding = false;
+      maybeRunPendingConfigReload();
+    });
+    watcher.on('build:failure', () => {
+      sourceBuilding = false;
+      maybeRunPendingConfigReload();
+    });
+  }
+
+  function wireDevSourceReload(watcher) {
+    watcher.on('build:success', ({ initial }) => {
+      if (!initial && liveReloadEnabled && liveReload) {
+        liveReload.broadcastReload();
+      }
+    });
+  }
+
+  function beginConfigWatching() {
+    if (configWatcher || stopping) {
+      return;
+    }
+
+    configWatcher = chokidar.watch(configPath, {
+      ignoreInitial: true,
+      persistent: true,
+      awaitWriteFinish: {
+        stabilityThreshold: 50,
+        pollInterval: 25,
+      },
+    });
+
+    configWatcher.on('all', (eventName) => {
+      if (
+        eventName === 'add' ||
+        eventName === 'change' ||
+        eventName === 'unlink'
+      ) {
+        queueConfigReload(eventName);
+      }
+    });
+
+    configWatcher.on('error', (err) => {
+      const message = err && err.message ? err.message : String(err);
+      console.error(`[JSKim] 設定ファイルの監視エラー: ${message}`);
+    });
+  }
+
+  function queueConfigReload(eventName) {
+    if (stopping) {
+      return;
+    }
+
+    if (eventName === 'unlink') {
+      console.log(
+        `[JSKim] 設定ファイルが一時的に削除されました。以前の正常な設定を継続します。`
+      );
+    } else {
+      console.log('[JSKim] 設定ファイルの変更を検出しました。');
+    }
+
+    if (configDebounceTimer) {
+      clearTimeout(configDebounceTimer);
+    }
+
+    const debounceMs =
+      currentProject && currentProject.watch
+        ? currentProject.watch.debounce
+        : 150;
+
+    configDebounceTimer = setTimeout(() => {
+      configDebounceTimer = null;
+      requestConfigReload();
+    }, debounceMs);
+  }
+
+  function requestConfigReload() {
+    if (stopping) {
+      return;
+    }
+
+    if (configReloadPromise || sourceBuilding) {
+      pendingConfigReload = true;
+      return;
+    }
+
+    configReloadPromise = (async () => {
+      try {
+        await performConfigReload();
+      } finally {
+        configReloadPromise = null;
+        if (!stopping && pendingConfigReload) {
+          pendingConfigReload = false;
+          requestConfigReload();
+        }
+      }
+    })();
+  }
+
+  function maybeRunPendingConfigReload() {
+    if (!stopping && pendingConfigReload && !configReloadPromise) {
+      pendingConfigReload = false;
+      requestConfigReload();
+    }
+  }
+
+  async function performConfigReload() {
+    if (stopping) {
+      return;
+    }
+
+    if (!fs.existsSync(configPath)) {
+      // unlink 後まだ復元されていない
+      return;
+    }
+
+    let candidate;
+    try {
+      const loaded = loadConfig(workspaceRoot);
+      candidate = resolveProject({
+        config: loaded.config,
+        workspaceRoot,
+        projectName,
+        commandName,
+        usageLine,
+      });
+    } catch (err) {
+      const message = err && err.message ? err.message : String(err);
+      console.error('[JSKim] 設定ファイルの再読み込みに失敗しました。');
+      console.error(message);
+      console.error('[JSKim] 以前の正常な設定を継続します。');
+      return;
+    }
+
+    if (mode === 'dev') {
+      const restartKeys = getRestartRequiredChanges(currentProject, candidate);
+      if (restartKeys.length > 0) {
+        console.warn(
+          '[JSKim] 次の設定変更を反映するにはdev processの再起動が必要です:'
+        );
+        for (const key of restartKeys) {
+          console.warn(`- ${key}`);
+        }
+        console.warn('[JSKim] 以前の正常な設定を継続します。');
+        return;
+      }
+    }
+
+    console.log('[JSKim] 設定を再読み込みしました。');
+
+    let buildSucceeded = false;
+    try {
+      await replaceProjectWatcher(candidate, {
+        onInitialBuildSuccess: () => {
+          buildSucceeded = true;
+        },
+        onInitialBuildFailure: () => {
+          buildSucceeded = false;
+        },
+      });
+      currentProject = candidate;
+      console.log('[JSKim] 監視対象を更新しました。');
+      if (mode === 'watch') {
+        console.log('パス:');
+        for (const display of projectWatcher.displayPaths) {
+          console.log(`- ${display}`);
+        }
+        console.log(`Debounce: ${projectWatcher.debounceMs}ms`);
+      }
+    } catch (err) {
+      const message = err && err.message ? err.message : String(err);
+      console.error('[JSKim] 設定の再読み込み後に監視の更新に失敗しました。');
+      console.error(message);
+      console.error('[JSKim] 以前の正常な設定を継続します。');
+      return;
+    }
+
+    if (!buildSucceeded) {
+      console.error(
+        '[JSKim] 設定の再読み込み後にbuildが失敗しました。監視は新しい設定で継続します。'
+      );
+      return;
+    }
+
+    if (mode === 'dev' && liveReloadEnabled && liveReload) {
+      liveReload.broadcastReload();
+    }
+  }
+
+  async function replaceProjectWatcher(project, hooks = {}) {
+    if (projectWatcher) {
+      try {
+        await projectWatcher.close();
+      } catch {
+        // reload 時の close エラーは無視
+      }
+      projectWatcher = null;
+    }
+
+    projectWatcher = createProjectWatcher(project, {
+      runInitialBuild: true,
+      logChanges: true,
+    });
+
+    wireSourceBuildTracking(projectWatcher);
+    if (mode === 'dev') {
+      wireDevSourceReload(projectWatcher);
+    }
+
+    const onSuccess = ({ initial }) => {
+      if (initial && hooks.onInitialBuildSuccess) {
+        hooks.onInitialBuildSuccess();
+      }
+    };
+    const onFailure = ({ initial }) => {
+      if (initial && hooks.onInitialBuildFailure) {
+        hooks.onInitialBuildFailure();
+      }
+    };
+    projectWatcher.on('build:success', onSuccess);
+    projectWatcher.on('build:failure', onFailure);
+
+    await projectWatcher.start();
+  }
+
+  async function cleanupDevComponents() {
+    if (projectWatcher) {
+      try {
+        await projectWatcher.close();
+      } catch {
+        // ignore
+      }
+      projectWatcher = null;
+    }
+    if (liveReload) {
+      try {
+        liveReload.close();
+      } catch {
+        // ignore
+      }
+      liveReload = null;
+    }
+    if (staticServer) {
+      try {
+        await staticServer.stop();
+      } catch {
+        // ignore
+      }
+      staticServer = null;
+    }
+  }
+
+  async function close() {
+    if (stopping) {
+      return;
+    }
+    stopping = true;
+
+    if (configDebounceTimer) {
+      clearTimeout(configDebounceTimer);
+      configDebounceTimer = null;
+    }
+
+    if (configWatcher) {
+      try {
+        await configWatcher.close();
+      } catch {
+        // ignore
+      }
+      configWatcher = null;
+    }
+
+    if (configReloadPromise) {
+      try {
+        await configReloadPromise;
+      } catch {
+        // ignore
+      }
+    }
+
+    if (mode === 'dev') {
+      await cleanupDevComponents();
+    } else if (projectWatcher) {
+      try {
+        await projectWatcher.close();
+      } catch {
+        // ignore
+      }
+      projectWatcher = null;
+    }
+  }
+
+  return {
+    start,
+    close,
+    get project() {
+      return currentProject;
+    },
+    get configFileName() {
+      return CONFIG_FILENAME;
+    },
+  };
+}
+
+/**
+ * @param {object} previous
+ * @param {object} next
+ * @returns {string[]}
+ */
+function getRestartRequiredChanges(previous, next) {
+  const changes = [];
+  if (previous.outputDir !== next.outputDir) {
+    changes.push('outputDir');
+  }
+  if (previous.serve.host !== next.serve.host) {
+    changes.push('serve.host');
+  }
+  if (previous.serve.port !== next.serve.port) {
+    changes.push('serve.port');
+  }
+  if (previous.dev.liveReload !== next.dev.liveReload) {
+    changes.push('dev.liveReload');
+  }
+  return changes;
+}
+
+function toDisplayPath(abs, workspaceRoot) {
+  const resolved = path.resolve(abs);
+  const rel = path.relative(workspaceRoot, resolved);
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) {
+    return resolved.split(path.sep).join('/');
+  }
+  return rel.split(path.sep).join('/');
+}
+
+module.exports = {
+  createWatchRuntime,
+  getRestartRequiredChanges,
+  DEV_RESTART_KEYS,
+};