@ywal123456/jskim 0.1.1 → 0.3.0

package/docs/configuration.md

@@ -2,50 +2,33 @@
 
 `jskim.config.js` はワークスペースルート（コマンドを実行した `process.cwd()`）に置き、すべてのビルド動作の基準になります。npm パッケージとして入れた場合も、インストール先ではなく実行時のカレントディレクトリをルートとして扱います。
 
-## 全体例
+## 推奨設定例
 
 ```js
 module.exports = {
   defaults: {
-    render: [
-      {
-        from: 'pages',
-        to: '',
-        include: ['**/*.njk'],
-        extension: '.html',
+    files: [{ from: 'pages', to: '' }],
+    templates: ['layouts', 'components'],
+    data: {
+      site: { name: 'JSKim Sample', language: 'ja' },
+    },
+    nunjucks: {
+      filters: {
+        formatPrice(value) {
+          return `${Number(value).toLocaleString('ja-JP')}円`;
+        },
       },
-    ],
-
-    templates: [
-      'layouts',
-      'components',
-    ],
-
-    copy: [
-      {
-        from: 'assets',
-        to: 'assets',
+      globals: {
+        currentYear() {
+          return new Date().getFullYear();
+        },
       },
-    ],
-
-    build: {
-      clean: true,
-    },
-
-    watch: {
-      debounce: 150,
-    },
-
-    serve: {
-      host: '127.0.0.1',
-      port: 3000,
-    },
-
-    dev: {
-      liveReload: true,
     },
+    build: { clean: true },
+    watch: { debounce: 150 },
+    serve: { host: '127.0.0.1', port: 3000 },
+    dev: { liveReload: true },
   },
-
   projects: {
     sample: {
       sourceDir: 'src/sample',
@@ -55,15 +38,9 @@ module.exports = {
 };
 ```
 
-## defaults
-
-すべてのプロジェクトに共通で適用される既定値です。
-
-プロジェクトに同じキーがあれば、プロジェクト側が優先されます。
+## defaults / projects
 
-## projects
-
-プロジェクト名 → 設定オブジェクトのマップです。
+`defaults` はすべてのプロジェクトに共通で適用される既定値です。`projects` はプロジェクト名から設定オブジェクトへのマップです。
 
 ```bash
 npm run build -- sample
@@ -81,46 +58,75 @@ npm run dev -- sample
 
 任意:
 
-- `render`, `templates`, `copy`, `build`, `watch`, `serve`, `dev` — defaults の上書き
+- `files`, `render`, `templates`, `copy`, `data`, `nunjucks`, `build`, `watch`, `serve`, `dev`
 
-## sourceDir
+## mode selection
 
-プロジェクトのソースルートです。**ワークスペースルート**基準の相対パス（または絶対パス）です。
+JSKim には 2 つの build mode があります。
 
-例: `src/sample`
+| mode | 条件 | 用途 |
+|------|------|------|
+| files mode | `files` が空でない配列 | v0.3.0 以降の推奨。Nunjucks と静的ファイルを同じルールで扱う |
+| legacy mode | `files` 未設定、かつ `render` が空でない配列 | 既存の `render` / `copy` 設定を継続する |
 
-## outputDir
+同じプロジェクトで `files` と `render` / `copy` は同時に設定できません。files mode を使う場合は `render` / `copy` を空にしてください。legacy mode を使う場合は `files` を設定しないでください。
 
-ビルド結果のルートです。**ワークスペースルート**基準です。
+## sourceDir / outputDir
 
-例: `dist/sample`
+`sourceDir` はプロジェクトのソースルートです。`outputDir` はビルド結果のルートです。どちらも **ワークスペースルート** 基準の相対パス（または絶対パス）です。
 
-`serve` はこのディレクトリを静的サーバーのルートとして公開します。
+```js
+projects: {
+  sample: {
+    sourceDir: 'src/sample',
+    outputDir: 'dist/sample',
+  },
+},
+```
 
-## render
+`serve` は `outputDir` を静的サーバーのルートとして公開します。
 
-Nunjucks ファイルを HTML にレンダリングするルール配列です。
+## files
 
-| フィールド | 基準 | 説明 |
-|------|------|------|
-| `from` | sourceDir | 探索開始ディレクトリ |
-| `to` | outputDir | 出力基準ディレクトリ（`''` = 出力ルート） |
-| `include` | from 基準 | glob パターン配列 |
-| `extension` | — | 出力拡張子（例: `.html`） |
+files mode の処理ルール配列です。
+
+| フィールド | 基準 | 必須 | 説明 |
+|------|------|------|------|
+| `from` | sourceDir | 必須 | 探索開始ディレクトリ |
+| `to` | outputDir | 任意 | 出力基準ディレクトリ。未指定または `''` は出力ルート |
+| `include` | from 基準 | 任意 | glob パターン配列。既定は `['**/*']` |
+| `exclude` | from 基準 | 任意 | 除外 glob パターン配列。既定は `[]` |
+
+処理:
+
+- 末尾が `.njk` のファイルは Nunjucks でレンダリングし、末尾の `.njk` だけを外して出力する
+- それ以外のファイルは byte copy する
+- 出力先が同じになるファイルが複数ある場合はエラーにする
+- `templates[]` 配下のファイルは直接出力しない
 
 例:
 
 ```text
-src/sample/pages/index.njk        → dist/sample/index.html
-src/sample/pages/guide/basic.njk  → dist/sample/guide/basic.html
+src/sample/pages/index.html.njk             → dist/sample/index.html
+src/sample/pages/assets/css/style.css.njk   → dist/sample/assets/css/style.css
+src/sample/pages/assets/image/logo.svg      → dist/sample/assets/image/logo.svg
 ```
 
-`layouts` と `components` は render 対象ではなく、直接出力されません。
+推奨命名:
+
+- HTML: `index.html.njk`
+- CSS: `style.css.njk`
+- JS: `main.js.njk`
+- Nunjucks 処理しない画像など: `logo.svg`
 
 ## templates
 
 Nunjucks loader の追加検索パスです。**sourceDir** 基準です。
 
+```js
+templates: ['layouts', 'components'],
+```
+
 `sourceDir` 自体も常に loader root に含まれるため、次が動作します。
 
 ```njk
@@ -128,112 +134,164 @@ Nunjucks loader の追加検索パスです。**sourceDir** 基準です。
 {% include "components/header.njk" %}
 ```
 
-## copy
+files mode では、`templates` に指定された既存ディレクトリ配下のファイルは直接出力から除外されます。layout / component を `files[].from` の範囲内に置いた場合でも、`templates` として指定しておけば出力対象になりません。
 
-静的ファイルを変換せずにコピーするルール配列です。
+## data
 
-| フィールド | 基準 | 説明 |
-|------|------|------|
-| `from` | sourceDir | コピー元 |
-| `to` | outputDir | コピー先 |
+`data` はすべての Nunjucks レンダリング context に渡される plain object です。
 
-`from` が無い場合は警告のみ出してビルドを続行します。
+```js
+data: {
+  site: {
+    name: 'JSKim Sample',
+    language: 'ja',
+    themeColor: '#222222',
+  },
+  samplePrice: 12000,
+},
+```
 
-## build.clean
+テンプレートでは通常の変数として参照できます。
 
-`true` のとき、ビルド前に `outputDir` だけを整理します。
+```njk
+<html lang="{{ site.language }}">
+{{ samplePrice }}
+```
 
-次のパスは削除せず、該当すればエラーで終了します。
+`rootPath` は JSKim が注入する予約キーです。`data.rootPath` は使えません。
 
-- ファイルシステムルート
-- ワークスペースルート
-- sourceDir 自体
-- sourceDir の上位パス
-- 空のパス
+機密情報を `data` に入れると、生成済み HTML / JS / CSS に出力される可能性があります。API key、token、社内 URL などの secret は入れないでください。
 
-## watch.debounce
+## nunjucks.filters / nunjucks.globals
 
-ファイル変更後、全体再ビルドを開始するまでの待ち時間（ms）です。
+Nunjucks のカスタム filter / global を `jskim.config.js` から登録できます。
 
-| 項目 | 内容 |
-|------|------|
-| 型 | `number`（有限の非負数） |
-| 既定値 | `150` |
-| マージ | `build` と同様にオブジェクト 1 段階マージ — プロジェクトで `watch.debounce` だけ上書き可能 |
+```js
+nunjucks: {
+  filters: {
+    formatPrice(value) {
+      return `${Number(value).toLocaleString('ja-JP')}円`;
+    },
+    toJson(value) {
+      const nunjucks = require('nunjucks');
+      return new nunjucks.runtime.SafeString(JSON.stringify(value));
+    },
+  },
+  globals: {
+    currentYear() {
+      return new Date().getFullYear();
+    },
+  },
+},
+```
+
+filter は function である必要があります。global は function 以外の値も登録できます。非同期 filter / global は現在サポートしていません。
+
+Nunjucks は `autoescape: true` です。JavaScript テンプレートへ JSON を埋め込む場合は、HTML escape されないよう `SafeString` を返す filter を使ってください。
+
+```njk
+const site = {{ site | toJson }};
+```
+
+## legacy render / copy
 
-プロジェクト別の上書き例:
+既存プロジェクト向けに `render` / `copy` は継続サポートします。
 
 ```js
-projects: {
-  sample: {
-    sourceDir: 'src/sample',
-    outputDir: 'dist/sample',
-    watch: {
-      debounce: 300,
+defaults: {
+  render: [
+    {
+      from: 'pages',
+      to: '',
+      include: ['**/*.njk'],
+      extension: '.html',
     },
-  },
+  ],
+  templates: ['layouts', 'components'],
+  copy: [
+    {
+      from: 'assets',
+      to: 'assets',
+    },
+  ],
 },
 ```
 
-不正な値:
+### render
 
-- 負数
-- 数値でない
-- `NaN` / `Infinity`
+Nunjucks ファイルを HTML などへレンダリングするルール配列です。
 
-この場合は設定エラーで終了します。
+| フィールド | 基準 | 説明 |
+|------|------|------|
+| `from` | sourceDir | 探索開始ディレクトリ |
+| `to` | outputDir | 出力基準ディレクトリ（`''` = 出力ルート） |
+| `include` | from 基準 | glob パターン配列 |
+| `extension` | — | 出力拡張子（例: `.html`） |
 
-注意:
+legacy render では `pages/index.njk` を `index.html` のように出力する構成が一般的です。
 
-- この段階では `jskim.config.js` 自体は watch しません
-- 設定を変えた場合は watch コマンドを再起動してください
+### copy
 
-## serve.host
+静的ファイルを変換せずにコピーするルール配列です。
 
-ローカル静的サーバーのバインドホストです。
+| フィールド | 基準 | 説明 |
+|------|------|------|
+| `from` | sourceDir | コピー元 |
+| `to` | outputDir | コピー先 |
 
-| 項目 | 内容 |
-|------|------|
-| 型 | 空でない `string` |
-| 既定値 | `'127.0.0.1'` |
-| マージ | `serve` オブジェクトの 1 段階マージ |
+`from` が無い場合は警告のみ出してビルドを続行します。
+
+## collision
+
+files mode では出力パスの衝突を検出します。たとえば同じ `files` 範囲に `about.html` と `about.html.njk` がある場合、どちらも `about.html` に出力されるためエラーになります。Windows では大文字小文字の違いだけの衝突も同じ出力として扱います。
+
+## rootPath
+
+各 `.njk` ファイルの最終出力位置を基準に `rootPath` が自動計算され、Nunjucks context に注入されます。
+
+```njk
+<link rel="stylesheet" href="{{ rootPath }}assets/css/style.css">
+<a href="{{ rootPath }}index.html">Home</a>
+```
 
-不正な値（空文字・非文字列）は設定エラーで終了します。
+| 出力ファイル | rootPath |
+|-----------|----------|
+| `dist/sample/index.html` | `./` |
+| `dist/sample/request/index.html` | `../` |
+| `dist/sample/guide/syntax/index.html` | `../../` |
 
-## serve.port
+## build.clean
 
-ローカル静的サーバーのポートです。
+`true` のとき、ビルド前に `outputDir` だけを整理します。
+
+次のパスは削除せず、該当すればエラーで終了します。
+
+- ファイルシステムルート
+- ワークスペースルート
+- sourceDir 自体
+- sourceDir の上位パス
+- 空のパス
+
+## watch.debounce
+
+ファイル変更後、全体再ビルドを開始するまでの待ち時間（ms）です。
 
 | 項目 | 内容 |
 |------|------|
-| 型 | 整数 |
-| 範囲 | `1` 以上 `65535` 以下 |
-| 既定値 | `3000` |
-| マージ | `serve` オブジェクトの 1 段階マージ — `serve.port` だけ上書き可能 |
-
-プロジェクト別の上書き例:
+| 型 | `number`（有限の非負数） |
+| 既定値 | `150` |
+| マージ | `watch` オブジェクトの 1 段階マージ |
 
-```js
-projects: {
-  sample: {
-    sourceDir: 'src/sample',
-    outputDir: 'dist/sample',
-    serve: {
-      port: 4000,
-    },
-  },
-},
-```
+不正な値（負数、数値でない、`NaN` / `Infinity`）は設定エラーで終了します。
 
-不正な値の例: 文字列、小数、`NaN`、負数、`0`、`65536` 以上。
+## serve.host / serve.port
 
-エラー例:
+ローカル静的サーバーのバインドホストとポートです。
 
-```text
-[JSKim] 設定値が不正です: serve.port
-1から65535までの整数を指定してください。
-受け取った値: -1
-```
+| 設定 | 型 | 既定値 |
+|------|------|------|
+| `serve.host` | 空でない `string` | `'127.0.0.1'` |
+| `serve.port` | `1` 以上 `65535` 以下の整数 | `3000` |
 
 `serve` は自動ビルドしません。`outputDir` が無い場合は先に `npm run build -- <name>` を実行してください。
 
@@ -251,7 +309,7 @@ projects: {
 
 - `GET /_jskim/live-reload` で SSE を提供
 - HTML レスポンスにだけ client script を一時注入（`dist` には書き込まない）
-- **成功した再ビルドのあとだけ** `reload` event を送信
+- 成功した再ビルドのあとだけ `reload` event を送信
 
 `false` のとき:
 
@@ -259,64 +317,48 @@ projects: {
 - HTML への script 注入なし
 - build + watch + serve 自体は動作
 
-### 予約パス `/_jskim/live-reload`
-
-`dev.liveReload: true` のときだけ有効になる内部 SSE endpoint です。
+`/_jskim/live-reload` は内部予約パスです。プロジェクトの静的ファイルとしては使わないことを推奨します。
 
-- JSKim が予約するパスであり、プロジェクトの静的ファイルとしては使わないことを推奨します
-- `serve` コマンドでは有効になりません
-- `dev.liveReload: false` では有効になりません
-- パス自体を設定で変更するオプションはありません
-
-プロジェクト別の上書き例:
-
-```js
-projects: {
-  sample: {
-    sourceDir: 'src/sample',
-    outputDir: 'dist/sample',
-    dev: {
-      liveReload: false,
-    },
-  },
-},
-```
+## config hot reload
 
-不正な値（boolean 以外）は設定エラーで終了します。
+`watch` と `dev` はワークスペースルートの `jskim.config.js` を監視します。
 
-### dev が再利用する設定
+| コマンド | 動作 |
+|----------|------|
+| `build` | 実行時に config を 1 回読み込む。監視しない |
+| `serve` | 実行時に config を 1 回読み込む。監視しない。変更後は process 再起動が必要 |
+| `watch` | config 変更を hot apply。`outputDir` 変更も可。以前の outputDir は自動削除しない |
+| `dev` | build / watch 関連設定を hot apply。一部 runtime 設定は再起動が必要 |
 
-| 設定 | 用途 |
-|------|------|
-| `watch.debounce` | 変更後の再ビルド待ち時間 |
-| `serve.host` | 開発サーバーのホスト |
-| `serve.port` | 開発サーバーのポート |
-| `dev.liveReload` | ライブリロード on/off |
+`dev` では次の値が変わった candidate config は適用しません。
 
-`dev.host` / `dev.port` / `dev.debounce` は用意しません。
+- `outputDir`
+- `serve.host`
+- `serve.port`
+- `dev.liveReload`
 
-設定変更後は実行中の watcher/server は自動再構成されないため、`dev` / `watch` / `serve` を再起動してください。
+理由: server bind と serve root を安全に切り替えるには process 再起動が必要で、部分適用すると build output と serve root がずれるためです。
 
 ## パス基準のまとめ
 
 | 設定 | 基準 |
 |------|------|
 | `sourceDir`, `outputDir` | ワークスペースルート（`jskim.config.js` の場所） |
-| `render[].from`, `templates[]`, `copy[].from` | `sourceDir` |
-| `render[].to`, `copy[].to` | `outputDir` |
+| `files[].from`, `render[].from`, `templates[]`, `copy[].from` | `sourceDir` |
+| `files[].to`, `render[].to`, `copy[].to` | `outputDir` |
+| `files[].include`, `files[].exclude`, `render[].include` | 各 `from` |
 
 Windows / POSIX とも `node:path` で解釈します。HTML 内パス（`rootPath` など）は `/` を使います。
 
-## 配列マージ規則
+## マージ規則
 
 - **通常値**: プロジェクト設定があれば優先、なければ defaults
-- **オブジェクト**（`build`, `watch`, `serve`, `dev` など）: 1 段階マージ — 例: `build.clean`、`watch.debounce`、`serve.port`、`dev.liveReload` だけ上書き可能
-- **配列**（`render`, `templates`, `copy`）: プロジェクトに同じ配列があれば **defaults 配列を丸ごと置き換え**。項目単位の自動マージなし
+- **オブジェクト**（`build`, `watch`, `serve`, `dev`, `data`, `nunjucks`）: 1 段階マージ
+- **`nunjucks.filters` / `nunjucks.globals`**: それぞれ 1 段階マージ
+- **配列**（`files`, `render`, `templates`, `copy`）: プロジェクトに同じ配列があれば defaults 配列を丸ごと置き換え。項目単位の自動マージなし
 
 元の `defaults` とプロジェクト設定オブジェクトは変更しません。
 
 ## 外部パス
 
-`sourceDir` / `outputDir` にワークスペース外のパスを使うことは禁止しません。
-フレームワークは Git 構成やフォルダ配置を強制しません。
-ただし clean の安全装置（上記）は常に適用されます。
+`sourceDir` / `outputDir` にワークスペース外のパスを使うことは禁止しません。フレームワークは Git 構成やフォルダ配置を強制しません。ただし clean の安全装置は常に適用されます。

package/docs/create-jskim.md

@@ -7,8 +7,8 @@
 ## 役割
 
 - 新しい JSKim プロジェクトディレクトリを作る
-- 標準 `src/sample` と `jskim.config.js` を含める
-- 生成後の `npm install` / `git init` は **実行しない**
+- files pipeline 版の標準 `src/sample` と `jskim.config.js` を含める
+- 生成後の `npm install` / `git init` は実行しない
 
 ## 名称の区別
 
@@ -35,16 +35,31 @@ project/
 ├─ jskim.config.js
 ├─ README.md
 ├─ .gitignore
-└─ src/sample/
+└─ src/
+   └─ sample/
+      ├─ pages/
+      │  ├─ index.html.njk
+      │  ├─ assets/
+      │  │  ├─ css/style.css.njk
+      │  │  ├─ js/main.js.njk
+      │  │  └─ image/logo.svg
+      │  └─ request/
+      │     ├─ index.html.njk
+      │     └─ assets/
+      ├─ layouts/base.njk
+      └─ components/
+         ├─ header.njk
+         └─ footer.njk
 ```
 
-`package.json` の scripts は bin 名 `jskim` を使います（package name ではありません）。
-既定の engine dependency は `@ywal123456/jskim`（`^0.1.0`）です。
+`jskim.config.js` は `files: [{ from: 'pages', to: '' }]` を使います。`.njk` は末尾の `.njk` だけを外してレンダリングし、画像などはそのままコピーします。
+
+`package.json` の scripts は bin 名 `jskim` を使います（package name ではありません）。既定の engine dependency は `@ywal123456/jskim`（`^0.3.0`）です。
 
 ```json
 {
   "devDependencies": {
-    "@ywal123456/jskim": "^0.1.0"
+    "@ywal123456/jskim": "^0.3.0"
   },
   "scripts": {
     "build": "jskim build sample",
@@ -70,7 +85,7 @@ create package の `package.json` に `jskimEngine` metadata を持ち、生成
 {
   "jskimEngine": {
     "packageName": "@ywal123456/jskim",
-    "version": "^0.1.0"
+    "version": "^0.3.0"
   }
 }
 ```

package/package.json

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