@ywal123456/jskim 0.1.0 → 0.2.0

package/README.md

@@ -25,14 +25,15 @@ Nunjucks ソースを設定に従って静的 HTML にレンダリングし、as
 
 - ブラウザ自動起動
 - HMR / CSS だけのホット更新
-- HTML 移行
 - JSON データの自動読み込み
 - API / Mock API
-- 実際の npm registry publish（手順は準備済み）
-- config の hot reload
 - 増分ビルド
 - SPA fallback / proxy
 
+既存 HTML の自動 import / migration は JSKim core の責任範囲外です。
+既存 source の移行は利用者が project に合わせて行います。
+将来必要になった場合も、JSKim 本体ではなく独立した tool / package として検討します。
+
 ## パッケージの役割
 
 | 名称 | 種類 | 役割 |
@@ -43,28 +44,38 @@ Nunjucks ソースを設定に従って静的 HTML にレンダリングし、as
 
 製品名は **JSKim**、CLI binary は **`jskim`**、npm engine package は **`@ywal123456/jskim`** です。package 名と binary 名を混同しないでください。
 
-Package 名・CLI 構造は公開名に合わせてあります。**このリポジトリ作業では registry への publish は行っていません**。registry からのインストールは publish 後に可能です。scoped engine は公開 MIT package として配布する予定です。
+`@ywal123456/jskim` と `create-jskim` は npm registry で公開済みの MIT package です。
 
 詳細:
 
 - [docs/create-jskim.md](docs/create-jskim.md)
-- [docs/publishing.md](docs/publishing.md)
-
-## パッケージとしての利用
+- [docs/publishing.md](docs/publishing.md)（maintainer 向け release 手順）
 
-公開後のインストール例:
+## インストール
 
 ```bash
 npm install --save-dev @ywal123456/jskim
 ```
 
+## 新規 project の作成
+
 ```bash
-jskim build sample
-jskim watch sample
-jskim serve sample
-jskim dev sample
+npm create jskim@latest
+```
 
-npx jskim build sample
+代替:
+
+```bash
+npx create-jskim my-project
+```
+
+## CLI
+
+```bash
+jskim build <project>
+jskim watch <project>
+jskim serve <project>
+jskim dev <project>
 ```
 
 `package.json` の scripts 例:
@@ -83,11 +94,11 @@ npx jskim build sample
 要点:
 
 - npm package 名は `@ywal123456/jskim`（scoped）
-- インストール後の CLI binary 名は `jskim`（変更なし）
+- インストール後の CLI binary 名は `jskim`
 - コマンドは実行したディレクトリの `process.cwd()` をプロジェクトルートとして扱う
 - パッケージのインストール先（`node_modules/@ywal123456/jskim`）を作業空間とはみなさない
 - プロジェクトルートに `jskim.config.js` が必要
-- `create-jskim` package と `npm create jskim@latest` コマンドは維持します
+
 ヘルプ / バージョン:
 
 ```bash
@@ -97,18 +108,13 @@ jskim --version
 
 ## プロジェクト生成（create-jskim）
 
-公開後の例:
-
 ```bash
 npm create jskim@latest
 # または
 npx create-jskim my-project
 ```
 
-ローカル / 開発時:
-
 ```bash
-create-jskim my-project
 cd my-project
 npm install
 npm run dev
@@ -116,7 +122,6 @@ npm run dev
 
 - 自動で `npm install` / `git init` は実行しません
 - 空ではない既存ディレクトリは上書きしません
-- 実際の registry インストールは publish 後に利用できます
 
 ## このリポジトリでの開発コマンド
 
@@ -167,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）
@@ -234,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

@@ -2,7 +2,7 @@
 
 `create-jskim` は JSKim の作業空間を新規作成する **独立 scaffold package** です。
 
-エンジン CLI（`jskim build` など）とは別 package として管理します。
+エンジン CLI（`jskim build` など）とは別 package として管理します。npm registry で公開済みです。
 
 ## 役割
 
@@ -18,7 +18,14 @@
 | `jskim` | CLI binary |
 | `@ywal123456/jskim` | npm engine package |
 | `create-jskim` | npm creator package |
-| `npm create jskim@latest` | ユーザー向け生成コマンド（維持） |
+| `npm create jskim@latest` | ユーザー向け生成コマンド |
+
+## 使い方
+
+```bash
+npm create jskim@latest
+npx create-jskim my-project
+```
 
 ## 生成結果
 
@@ -32,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",
@@ -63,18 +70,11 @@ create package の `package.json` に `jskimEngine` metadata を持ち、生成
 {
   "jskimEngine": {
     "packageName": "@ywal123456/jskim",
-    "version": "^0.1.0"
+    "version": "^0.2.0"
   }
 }
 ```
 
 生成プロジェクトへ License は強制しません。
 
-## 公開コマンド（publish 後）
-
-```bash
-npm create jskim@latest
-npx create-jskim my-project
-```
-
-Package 名・CLI 構造は上記に合わせて準備済みです。registry への実際の publish は別手順です（[publishing.md](./publishing.md)）。
+Maintainer 向けの release / publish 手順は [publishing.md](./publishing.md) を参照してください。

package/docs/publishing.md

@@ -1,18 +1,22 @@
 # 公開手順（publishing）
 
-この文書は **将来の実際の publish 手順** をまとめたものです。
+この文書は **maintainer 向けの release / publish 手順** です。
 開発リポジトリの通常作業では `npm publish` を実行しません。
 
-## 前提
+## 現在公開中
 
-- npm アカウントと認証（2FA ポリシーを含む）
-- 公開 package 名
-  - engine: `@ywal123456/jskim`（scoped・公開 MIT）
-  - creator: `create-jskim`（unscoped）
+```text
+engine: @ywal123456/jskim
+creator: create-jskim
+CLI binary: jskim / create-jskim
+license: MIT
+```
+
+初回公開（v0.1.0）は完了しています。以降の patch / minor release でも、同じ手順で engine を先に、creator を後に公開します。
 
 ### 過去の失敗（参考）
 
-unscoped 名 `jskim@0.1.0` の初回 publish は、npm の package name similarity ポリシーにより **E403** で拒否されました。registry には反映されていません。現在の engine 公開名は `@ywal123456/jskim` です。
+unscoped 名での初回 engine publish は、npm の package name similarity ポリシーにより拒否されました。現在の engine 公開名は `@ywal123456/jskim` です。
 
 ### 確定済み metadata
 
@@ -38,15 +42,7 @@ Root `package.json` の `publishConfig`:
 }
 ```
 
-`publishConfig` があっても、scoped engine の初回 publish では手動コマンドの `--access public` を省略しないでください。
-
-### 残りの運用判断
-
-```text
-- 実際の npm publish 時点
-- npm アカウントのログイン状態
-- npm 2FA 状態
-```
+scoped engine の publish では手動コマンドの `--access public` を省略しないでください。
 
 ## 認証とセキュリティ
 
@@ -55,51 +51,41 @@ Root `package.json` の `publishConfig`:
 - token をソースコードや文書に記録しないでください
 - `.npmrc` の認証情報を repository に含めないでください
 - publish 直前に `npm whoami` でログイン状態を確認してください
-- 公開前に会社固有情報・secret・内部 URL が残っていないことを確認してください
+- 公開作業の前に会社固有情報・secret・内部 URL が残っていないことを確認してください
 
-## 推奨順序
+## 推奨順序（patch / minor）
 
 Engine を先に publish します。生成プロジェクトの `package.json` が `@ywal123456/jskim` を参照するため、creator だけ先に公開すると生成直後の `npm install` が失敗し得ます。
 
-1. npm account と認証状態を確認する
-2. package 名を再確認する（`@ywal123456/jskim` / `create-jskim`）
-3. リポジトリ root で `npm test` を実行する
-4. engine の `npm pack` / `npm publish --dry-run --access public` を確認する
-5. creator の `npm pack` / `npm publish --dry-run` を確認する
-6. **engine を先に publish** する（`--access public` 必須）
+1. version を決定する
+2. リポジトリ root で `npm test` を実行する
+3. engine / creator の `npm pack` を確認する
+4. `npm publish --dry-run` を確認する
+5. Git commit / push する
+6. **engine を先に publish** する（`--access public`）
 7. registry から engine をインストールできることを確認する
 8. creator を publish する
 9. `npm create jskim@latest` を検証する
+10. Git tag と GitHub Release を作成する
 
-## コマンド例（ユーザーが実行）
+同じ name / version を再 publish できると仮定しないでください。
 
-リポジトリ root（PowerShell）:
+## コマンド例（PowerShell）
+
+Engine（リポジトリ root）:
 
 ```powershell
 npm.cmd whoami --registry=https://registry.npmjs.org
-npm.cmd view @ywal123456/jskim name version --registry=https://registry.npmjs.org
-npm.cmd view create-jskim name version --registry=https://registry.npmjs.org
 npm.cmd test
 npm.cmd publish --dry-run --access public --registry=https://registry.npmjs.org
 npm.cmd publish --access public --registry=https://registry.npmjs.org
 ```
 
-期待する成功出力:
-
-```text
-+ @ywal123456/jskim@0.1.0
-```
-
-Registry 確認:
+Registry / インストール確認:
 
 ```powershell
-npm.cmd view @ywal123456/jskim@0.1.0 name version license bin repository --registry=https://registry.npmjs.org
-```
-
-外部インストール:
-
-```powershell
-npm.cmd install --save-dev @ywal123456/jskim@0.1.0 --registry=https://registry.npmjs.org
+npm.cmd view @ywal123456/jskim name version dist-tags --registry=https://registry.npmjs.org
+npm.cmd install --save-dev @ywal123456/jskim --registry=https://registry.npmjs.org
 ```
 
 Creator:
@@ -110,25 +96,19 @@ npm.cmd publish --dry-run --registry=https://registry.npmjs.org
 npm.cmd publish --registry=https://registry.npmjs.org
 ```
 
-期待する成功出力:
-
-```text
-+ create-jskim@0.1.0
-```
-
 最終ユーザー検証:
 
 ```powershell
 npm.cmd create jskim@latest generated-project
-npx create-jskim my-project
 ```
 
 ## 注意
 
-- unscoped engine 向けの `npm publish`（`--access public` なし・旧 package 名）は使わないでください
-- lifecycle script（`prepublishOnly` など）は、creator を別 cwd から publish する構成との相性を考えて必須化していません
+- unscoped engine 向けの旧 package 名では publish しません
+- lifecycle script（`prepublishOnly` など）は必須化していません
 - publish 前チェックリストとして **手動の `npm test`** を必須とします
 - token 生成・login・owner / dist-tag 変更は運用者が責任を持って行います
 - 生成プロジェクトへ License を強制しません（ユーザー側で決定）
 - creator は unscoped public package のため、creator `package.json` に `access: public` は追加していません
-- dry-run 成功は、creator の similarity 審査通過を保証しません
+- 文書のみの修正でも npm package README を更新する場合は patch version を使います
+- 既存の公開 tag（例: `v0.1.0`）を移動または再作成しません

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ywal123456/jskim",
-  "version": "0.1.0",
+  "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,
+};