@ywal123456/jskim 0.1.0

package/docs/configuration.md

@@ -0,0 +1,322 @@
+# JSKim 設定
+
+`jskim.config.js` はワークスペースルート（コマンドを実行した `process.cwd()`）に置き、すべてのビルド動作の基準になります。npm パッケージとして入れた場合も、インストール先ではなく実行時のカレントディレクトリをルートとして扱います。
+
+## 全体例
+
+```js
+module.exports = {
+  defaults: {
+    render: [
+      {
+        from: 'pages',
+        to: '',
+        include: ['**/*.njk'],
+        extension: '.html',
+      },
+    ],
+
+    templates: [
+      'layouts',
+      'components',
+    ],
+
+    copy: [
+      {
+        from: 'assets',
+        to: 'assets',
+      },
+    ],
+
+    build: {
+      clean: true,
+    },
+
+    watch: {
+      debounce: 150,
+    },
+
+    serve: {
+      host: '127.0.0.1',
+      port: 3000,
+    },
+
+    dev: {
+      liveReload: true,
+    },
+  },
+
+  projects: {
+    sample: {
+      sourceDir: 'src/sample',
+      outputDir: 'dist/sample',
+    },
+  },
+};
+```
+
+## defaults
+
+すべてのプロジェクトに共通で適用される既定値です。
+
+プロジェクトに同じキーがあれば、プロジェクト側が優先されます。
+
+## projects
+
+プロジェクト名 → 設定オブジェクトのマップです。
+
+```bash
+npm run build -- sample
+npm run watch -- sample
+npm run serve -- sample
+npm run dev -- sample
+```
+
+上記の `sample` が `projects.sample` を指します。
+
+必須:
+
+- `sourceDir`
+- `outputDir`
+
+任意:
+
+- `render`, `templates`, `copy`, `build`, `watch`, `serve`, `dev` — defaults の上書き
+
+## sourceDir
+
+プロジェクトのソースルートです。**ワークスペースルート**基準の相対パス（または絶対パス）です。
+
+例: `src/sample`
+
+## outputDir
+
+ビルド結果のルートです。**ワークスペースルート**基準です。
+
+例: `dist/sample`
+
+`serve` はこのディレクトリを静的サーバーのルートとして公開します。
+
+## render
+
+Nunjucks ファイルを HTML にレンダリングするルール配列です。
+
+| フィールド | 基準 | 説明 |
+|------|------|------|
+| `from` | sourceDir | 探索開始ディレクトリ |
+| `to` | outputDir | 出力基準ディレクトリ（`''` = 出力ルート） |
+| `include` | from 基準 | glob パターン配列 |
+| `extension` | — | 出力拡張子（例: `.html`） |
+
+例:
+
+```text
+src/sample/pages/index.njk        → dist/sample/index.html
+src/sample/pages/guide/basic.njk  → dist/sample/guide/basic.html
+```
+
+`layouts` と `components` は render 対象ではなく、直接出力されません。
+
+## templates
+
+Nunjucks loader の追加検索パスです。**sourceDir** 基準です。
+
+`sourceDir` 自体も常に loader root に含まれるため、次が動作します。
+
+```njk
+{% extends "layouts/base.njk" %}
+{% include "components/header.njk" %}
+```
+
+## copy
+
+静的ファイルを変換せずにコピーするルール配列です。
+
+| フィールド | 基準 | 説明 |
+|------|------|------|
+| `from` | sourceDir | コピー元 |
+| `to` | outputDir | コピー先 |
+
+`from` が無い場合は警告のみ出してビルドを続行します。
+
+## build.clean
+
+`true` のとき、ビルド前に `outputDir` だけを整理します。
+
+次のパスは削除せず、該当すればエラーで終了します。
+
+- ファイルシステムルート
+- ワークスペースルート
+- sourceDir 自体
+- sourceDir の上位パス
+- 空のパス
+
+## watch.debounce
+
+ファイル変更後、全体再ビルドを開始するまでの待ち時間（ms）です。
+
+| 項目 | 内容 |
+|------|------|
+| 型 | `number`（有限の非負数） |
+| 既定値 | `150` |
+| マージ | `build` と同様にオブジェクト 1 段階マージ — プロジェクトで `watch.debounce` だけ上書き可能 |
+
+プロジェクト別の上書き例:
+
+```js
+projects: {
+  sample: {
+    sourceDir: 'src/sample',
+    outputDir: 'dist/sample',
+    watch: {
+      debounce: 300,
+    },
+  },
+},
+```
+
+不正な値:
+
+- 負数
+- 数値でない
+- `NaN` / `Infinity`
+
+この場合は設定エラーで終了します。
+
+注意:
+
+- この段階では `jskim.config.js` 自体は watch しません
+- 設定を変えた場合は watch コマンドを再起動してください
+
+## serve.host
+
+ローカル静的サーバーのバインドホストです。
+
+| 項目 | 内容 |
+|------|------|
+| 型 | 空でない `string` |
+| 既定値 | `'127.0.0.1'` |
+| マージ | `serve` オブジェクトの 1 段階マージ |
+
+不正な値（空文字・非文字列）は設定エラーで終了します。
+
+## serve.port
+
+ローカル静的サーバーのポートです。
+
+| 項目 | 内容 |
+|------|------|
+| 型 | 整数 |
+| 範囲 | `1` 以上 `65535` 以下 |
+| 既定値 | `3000` |
+| マージ | `serve` オブジェクトの 1 段階マージ — `serve.port` だけ上書き可能 |
+
+プロジェクト別の上書き例:
+
+```js
+projects: {
+  sample: {
+    sourceDir: 'src/sample',
+    outputDir: 'dist/sample',
+    serve: {
+      port: 4000,
+    },
+  },
+},
+```
+
+不正な値の例: 文字列、小数、`NaN`、負数、`0`、`65536` 以上。
+
+エラー例:
+
+```text
+[JSKim] 設定値が不正です: serve.port
+1から65535までの整数を指定してください。
+受け取った値: -1
+```
+
+`serve` は自動ビルドしません。`outputDir` が無い場合は先に `npm run build -- <name>` を実行してください。
+
+## dev.liveReload
+
+開発サーバー（`npm run dev`）のライブリロード有効/無効です。
+
+| 項目 | 内容 |
+|------|------|
+| 型 | `boolean` |
+| 既定値 | `true` |
+| マージ | `dev` オブジェクトの 1 段階マージ |
+
+`true` のとき:
+
+- `GET /_jskim/live-reload` で SSE を提供
+- HTML レスポンスにだけ client script を一時注入（`dist` には書き込まない）
+- **成功した再ビルドのあとだけ** `reload` event を送信
+
+`false` のとき:
+
+- SSE endpoint は提供しない（404）
+- HTML への script 注入なし
+- build + watch + serve 自体は動作
+
+### 予約パス `/_jskim/live-reload`
+
+`dev.liveReload: true` のときだけ有効になる内部 SSE endpoint です。
+
+- JSKim が予約するパスであり、プロジェクトの静的ファイルとしては使わないことを推奨します
+- `serve` コマンドでは有効になりません
+- `dev.liveReload: false` では有効になりません
+- パス自体を設定で変更するオプションはありません
+
+プロジェクト別の上書き例:
+
+```js
+projects: {
+  sample: {
+    sourceDir: 'src/sample',
+    outputDir: 'dist/sample',
+    dev: {
+      liveReload: false,
+    },
+  },
+},
+```
+
+不正な値（boolean 以外）は設定エラーで終了します。
+
+### dev が再利用する設定
+
+| 設定 | 用途 |
+|------|------|
+| `watch.debounce` | 変更後の再ビルド待ち時間 |
+| `serve.host` | 開発サーバーのホスト |
+| `serve.port` | 開発サーバーのポート |
+| `dev.liveReload` | ライブリロード on/off |
+
+`dev.host` / `dev.port` / `dev.debounce` は用意しません。
+
+設定変更後は実行中の watcher/server は自動再構成されないため、`dev` / `watch` / `serve` を再起動してください。
+
+## パス基準のまとめ
+
+| 設定 | 基準 |
+|------|------|
+| `sourceDir`, `outputDir` | ワークスペースルート（`jskim.config.js` の場所） |
+| `render[].from`, `templates[]`, `copy[].from` | `sourceDir` |
+| `render[].to`, `copy[].to` | `outputDir` |
+
+Windows / POSIX とも `node:path` で解釈します。HTML 内パス（`rootPath` など）は `/` を使います。
+
+## 配列マージ規則
+
+- **通常値**: プロジェクト設定があれば優先、なければ defaults
+- **オブジェクト**（`build`, `watch`, `serve`, `dev` など）: 1 段階マージ — 例: `build.clean`、`watch.debounce`、`serve.port`、`dev.liveReload` だけ上書き可能
+- **配列**（`render`, `templates`, `copy`）: プロジェクトに同じ配列があれば **defaults 配列を丸ごと置き換え**。項目単位の自動マージなし
+
+元の `defaults` とプロジェクト設定オブジェクトは変更しません。
+
+## 外部パス
+
+`sourceDir` / `outputDir` にワークスペース外のパスを使うことは禁止しません。
+フレームワークは Git 構成やフォルダ配置を強制しません。
+ただし clean の安全装置（上記）は常に適用されます。

package/docs/create-jskim.md

@@ -0,0 +1,80 @@
+# create-jskim
+
+`create-jskim` は JSKim の作業空間を新規作成する **独立 scaffold package** です。
+
+エンジン CLI（`jskim build` など）とは別 package として管理します。
+
+## 役割
+
+- 新しい JSKim プロジェクトディレクトリを作る
+- 標準 `src/sample` と `jskim.config.js` を含める
+- 生成後の `npm install` / `git init` は **実行しない**
+
+## 名称の区別
+
+| 名称 | 意味 |
+|------|------|
+| JSKim | 製品名 |
+| `jskim` | CLI binary |
+| `@ywal123456/jskim` | npm engine package |
+| `create-jskim` | npm creator package |
+| `npm create jskim@latest` | ユーザー向け生成コマンド（維持） |
+
+## 生成結果
+
+```text
+project/
+├─ package.json
+├─ jskim.config.js
+├─ README.md
+├─ .gitignore
+└─ src/sample/
+```
+
+`package.json` の scripts は bin 名 `jskim` を使います（package name ではありません）。
+既定の engine dependency は `@ywal123456/jskim`（`^0.1.0`）です。
+
+```json
+{
+  "devDependencies": {
+    "@ywal123456/jskim": "^0.1.0"
+  },
+  "scripts": {
+    "build": "jskim build sample",
+    "watch": "jskim watch sample",
+    "serve": "jskim serve sample",
+    "dev": "jskim dev sample"
+  }
+}
+```
+
+## 安全ポリシー
+
+- 空ではない既存ディレクトリは上書きしない
+- 隠しファイルがある場合も空ではないとみなす
+- 生成失敗時は今回作ったファイルだけを片付ける
+- template 内の `gitignore` を生成時に `.gitignore` へ変換する
+
+## エンジン dependency
+
+create package の `package.json` に `jskimEngine` metadata を持ち、生成プロジェクトの `devDependencies` に反映します。
+
+```json
+{
+  "jskimEngine": {
+    "packageName": "@ywal123456/jskim",
+    "version": "^0.1.0"
+  }
+}
+```
+
+生成プロジェクトへ License は強制しません。
+
+## 公開コマンド（publish 後）
+
+```bash
+npm create jskim@latest
+npx create-jskim my-project
+```
+
+Package 名・CLI 構造は上記に合わせて準備済みです。registry への実際の publish は別手順です（[publishing.md](./publishing.md)）。

package/docs/publishing.md

@@ -0,0 +1,134 @@
+# 公開手順（publishing）
+
+この文書は **将来の実際の publish 手順** をまとめたものです。
+開発リポジトリの通常作業では `npm publish` を実行しません。
+
+## 前提
+
+- npm アカウントと認証（2FA ポリシーを含む）
+- 公開 package 名
+  - engine: `@ywal123456/jskim`（scoped・公開 MIT）
+  - creator: `create-jskim`（unscoped）
+
+### 過去の失敗（参考）
+
+unscoped 名 `jskim@0.1.0` の初回 publish は、npm の package name similarity ポリシーにより **E403** で拒否されました。registry には反映されていません。現在の engine 公開名は `@ywal123456/jskim` です。
+
+### 確定済み metadata
+
+```text
+engine package: @ywal123456/jskim
+creator package: create-jskim
+CLI binary: jskim / create-jskim
+license: MIT
+author: Jeongsub Kim <ywal123456@gmail.com>
+repository: https://github.com/ywal123456-collab/jskim
+homepage: https://github.com/ywal123456-collab/jskim#readme
+bugs: https://github.com/ywal123456-collab/jskim/issues
+```
+
+Root `package.json` の `publishConfig`:
+
+```json
+{
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}
+```
+
+`publishConfig` があっても、scoped engine の初回 publish では手動コマンドの `--access public` を省略しないでください。
+
+### 残りの運用判断
+
+```text
+- 実際の npm publish 時点
+- npm アカウントのログイン状態
+- npm 2FA 状態
+```
+
+## 認証とセキュリティ
+
+- 実際の publish には npm account 認証が必要です
+- 2FA の有効化と運用ポリシーを確認してください
+- token をソースコードや文書に記録しないでください
+- `.npmrc` の認証情報を repository に含めないでください
+- publish 直前に `npm whoami` でログイン状態を確認してください
+- 公開前に会社固有情報・secret・内部 URL が残っていないことを確認してください
+
+## 推奨順序
+
+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` 必須）
+7. registry から engine をインストールできることを確認する
+8. creator を publish する
+9. `npm create jskim@latest` を検証する
+
+## コマンド例（ユーザーが実行）
+
+リポジトリ root（PowerShell）:
+
+```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 確認:
+
+```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
+```
+
+Creator:
+
+```powershell
+cd create-jskim
+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 する構成との相性を考えて必須化していません
+- publish 前チェックリストとして **手動の `npm test`** を必須とします
+- token 生成・login・owner / dist-tag 変更は運用者が責任を持って行います
+- 生成プロジェクトへ License を強制しません（ユーザー側で決定）
+- creator は unscoped public package のため、creator `package.json` に `access: public` は追加していません
+- dry-run 成功は、creator の similarity 審査通過を保証しません

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@ywal123456/jskim",
+  "version": "0.1.0",
+  "description": "Nunjucks-based static HTML build environment with watch, serve, and live reload",
+  "keywords": [
+    "nunjucks",
+    "static-html",
+    "static-site",
+    "build-tool",
+    "template-engine",
+    "live-reload",
+    "cli"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Jeongsub Kim",
+    "email": "ywal123456@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ywal123456-collab/jskim.git"
+  },
+  "homepage": "https://github.com/ywal123456-collab/jskim#readme",
+  "bugs": {
+    "url": "https://github.com/ywal123456-collab/jskim/issues"
+  },
+  "bin": {
+    "jskim": "bin/jskim.js"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "README.md",
+    "docs/",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node scripts/build.js",
+    "watch": "node scripts/watch.js",
+    "serve": "node scripts/serve.js",
+    "dev": "node scripts/dev.js",
+    "test": "node --test --test-concurrency=1 test/**/*.test.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "chokidar": "^3.6.0",
+    "fast-glob": "^3.3.3",
+    "fs-extra": "^11.3.0",
+    "nunjucks": "^3.2.4"
+  }
+}

package/scripts/build.js

@@ -0,0 +1,13 @@
+'use strict';
+
+const { runBuildCommand } = require('./commands/build-command');
+
+runBuildCommand({
+  projectName: process.argv[2],
+  workspaceRoot: process.cwd(),
+  usageLine: 'npm run build -- <project-name>',
+}).catch((err) => {
+  const message = err && err.message ? err.message : String(err);
+  console.error(message);
+  process.exitCode = 1;
+});

package/scripts/commands/build-command.js

@@ -0,0 +1,29 @@
+'use strict';
+
+const { buildProject } = require('../lib/build-project');
+
+/**
+ * build コマンドを実行します。
+ * @param {object} options
+ * @param {string|undefined} options.projectName
+ * @param {string} [options.workspaceRoot]
+ * @param {string} [options.usageLine]
+ * @returns {Promise<object>}
+ */
+async function runBuildCommand(options = {}) {
+  const workspaceRoot = options.workspaceRoot || process.cwd();
+  const usageLine =
+    options.usageLine || 'npm run build -- <project-name>';
+
+  return buildProject(options.projectName, {
+    workspaceRoot,
+    commandName: 'build',
+    usageLine,
+    logTitle: 'ビルドが完了しました',
+    includeOutput: true,
+  });
+}
+
+module.exports = {
+  runBuildCommand,
+};