@ywal123456/jskim 0.4.0 → 0.5.1

package/README.md

@@ -17,12 +17,13 @@ Nunjucks を使った汎用の静的 HTML ビルド環境です。
 - 成功した再ビルド後のライブリロード（SSE）
 - 再ビルド失敗時の browser error overlay（`dev` + `liveReload`）
 - 安全な CSS 変更時の stylesheet soft reload（`dev` + `liveReload`）
+- CLI 便利機能（`build --all`、project 省略、`--host` / `--port`、`dev --open`）
 - CLI binary `jskim`
 - プロジェクト生成 CLI `create-jskim`
 
 ## 現在の非対応範囲
 
-- ブラウザ自動起動
+- ブラウザ選択 option / `serve --open`
 - HMR / JavaScript module hot replacement
 - JSON / YAML などの外部データファイル自動読み込み
 - API / Mock API
@@ -60,6 +61,8 @@ npm install --save-dev @ywal123456/jskim
 
 ```bash
 npm create jskim@latest
+pnpm create jskim
+yarn create jskim
 ```
 
 代替:
@@ -68,15 +71,16 @@ npm create jskim@latest
 npx create-jskim my-project
 ```
 
-生成器は自動で `npm install` / `git init` を実行しません。空ではない既存ディレクトリも上書きしません。
+生成器は自動で `npm install` / `git init` を実行しません。空ではない既存ディレクトリも上書きしません。完了案内は実行した package manager に合わせた install / dev コマンドと、既定の開発 URL（`http://127.0.0.1:3000/`）を表示します。
 
 ## CLI
 
 ```bash
-jskim build <project>
-jskim watch <project>
-jskim serve <project>
-jskim dev <project>
+jskim build [<project>]
+jskim build --all
+jskim watch [<project>]
+jskim serve [<project>] [--host <host>] [--port <port>]
+jskim dev [<project>] [--host <host>] [--port <port>] [--open]
 ```
 
 `package.json` の scripts 例:
@@ -97,6 +101,11 @@ jskim dev <project>
 - コマンドは実行したディレクトリの `process.cwd()` をプロジェクトルートとして扱う
 - パッケージのインストール先（`node_modules/@ywal123456/jskim`）を作業空間とはみなさない
 - プロジェクトルートに `jskim.config.js` が必要
+- 設定内の project が 1 件だけのとき、project 名を省略できる
+- `build --all` は定義順に全 project を順次 build する。1 件でも失敗すれば exit code 1
+- `--host` / `--port` は serve / dev の CLI 上書き（config より優先）。`dev` の config hot reload 中も維持される
+- `dev --open` は listen 成功後に browser を 1 回開く。失敗しても warning のみで dev は継続する
+- option は project の前でも後ろでもよい（例: `jskim dev --port 4000 sample`）
 
 ヘルプ / バージョン:
 
@@ -208,7 +217,7 @@ jskim watch sample
 - legacy mode: `sourceDir` + `render[].from`、`sourceDir` + `templates[]`、`sourceDir` + `copy[].from`
 - `dist/`、`node_modules/`、`outputDir` は監視しません
 
-`watch` / `dev` は `jskim.config.js` の変更を検知し、正常なら監視対象を更新して全体ビルドします。`dev` で `outputDir` / `serve.host` / `serve.port` / `dev.liveReload` を変えた場合は process 再起動が必要です。
+`watch` / `dev` は `jskim.config.js` の変更を検知し、正常なら監視対象を更新して全体ビルドします。`dev` で effective な `outputDir` / `serve.host` / `serve.port` / `dev.liveReload` を変えた場合は process 再起動が必要です。CLI の `--host` / `--port` がある場合は、その上書き後の値で再起動要否を判定します。
 
 ## serve / dev
 
@@ -242,7 +251,9 @@ http://127.0.0.1:3000/
 - CSS ファイルだけが安全に変更された再ビルドでは、ページ全体ではなく stylesheet を更新します
 - CSS 以外の変更や判定が不確実な場合は、従来どおりページ全体 reload します
 - `dev` でも `dist` ファイルへ runtime は書き込みません
-- ブラウザ自動起動はサポートしません
+- `jskim serve|dev ... --host` / `--port` で待受を上書きできる（config より優先）
+- ポート衝突時は `--port` の例と `serve.port` 変更を案内する（自動で別 port は選ばない）
+- `jskim dev ... --open` で listen 成功後に browser を 1 回開く（失敗は warning、dev は継続）
 - 厳格な Content Security Policy で inline script または inline style が禁止されている場合、dev の live reload・error overlay・CSS soft reload が動作しないことがあります
 
 `/_jskim/live-reload` は `dev.liveReload: true` のときだけ使う内部予約パスです。実際の静的ファイルパスとしては使わないことを推奨します。

package/bin/jskim.js

@@ -2,14 +2,13 @@
 'use strict';
 
 const path = require('node:path');
-const { getHelpText, getUnknownCommandText } = require('../scripts/commands/help-text');
+const { getHelpText } = require('../scripts/commands/help-text');
+const { parseJskimArgv } = require('../scripts/lib/parse-cli-args');
 const { runBuildCommand } = require('../scripts/commands/build-command');
 const { runWatchCommand } = require('../scripts/commands/watch-command');
 const { runServeCommand } = require('../scripts/commands/serve-command');
 const { runDevCommand } = require('../scripts/commands/dev-command');
 
-const COMMANDS = new Set(['build', 'watch', 'serve', 'dev']);
-
 function readPackageVersion() {
   // package インストール先の package.json を読む（作業空間ではない）
   const pkg = require(path.join(__dirname, '..', 'package.json'));
@@ -28,72 +27,76 @@ function printVersion() {
  * @param {string[]} argv process.argv 相当（node と script を除く）
  */
 async function dispatch(argv) {
-  const first = argv[0];
-
-  if (!first) {
-    printHelp();
-    process.exitCode = 0;
+  let parsed;
+  try {
+    parsed = parseJskimArgv(argv);
+  } catch (err) {
+    const message = err && err.message ? err.message : String(err);
+    console.error(message);
+    process.exitCode = 1;
     return;
   }
 
-  if (first === '--help' || first === '-h' || first === 'help') {
+  if (parsed.kind === 'help') {
     printHelp();
     process.exitCode = 0;
     return;
   }
 
-  if (first === '--version' || first === '-v') {
+  if (parsed.kind === 'version') {
     printVersion();
     process.exitCode = 0;
     return;
   }
 
-  if (!COMMANDS.has(first)) {
-    console.error(getUnknownCommandText(first));
-    process.exitCode = 1;
-    return;
-  }
-
-  const projectName = argv[1];
+  const command = parsed.command;
+  const projectName = parsed.projectName;
+  const options = parsed.options;
   const workspaceRoot = process.cwd();
-  const usageLine = `jskim ${first} <project>`;
-  const buildHint = projectName
-    ? `jskim build ${projectName}`
-    : 'jskim build <project>';
 
-  if (first === 'build') {
+  if (command === 'build') {
     await runBuildCommand({
       projectName,
+      all: options.all,
       workspaceRoot,
-      usageLine,
+      usageLine: 'jskim build [<project>]',
     });
     return;
   }
 
-  if (first === 'watch') {
+  if (command === 'watch') {
     await runWatchCommand({
       projectName,
       workspaceRoot,
-      usageLine,
+      usageLine: 'jskim watch [<project>]',
     });
     return;
   }
 
-  if (first === 'serve') {
+  if (command === 'serve') {
+    const buildHint = projectName
+      ? `jskim build ${projectName}`
+      : 'jskim build [<project>]';
     await runServeCommand({
       projectName,
       workspaceRoot,
-      usageLine,
+      usageLine: 'jskim serve [<project>] [--host <host>] [--port <port>]',
       buildHint,
+      host: options.host,
+      port: options.port,
     });
     return;
   }
 
-  if (first === 'dev') {
+  if (command === 'dev') {
     await runDevCommand({
       projectName,
       workspaceRoot,
-      usageLine,
+      usageLine:
+        'jskim dev [<project>] [--host <host>] [--port <port>] [--open]',
+      host: options.host,
+      port: options.port,
+      open: options.open,
     });
   }
 }

package/docs/configuration.md

@@ -293,7 +293,23 @@ files mode では出力パスの衝突を検出します。たとえば同じ `f
 | `serve.host` | 空でない `string` | `'127.0.0.1'` |
 | `serve.port` | `1` 以上 `65535` 以下の整数 | `3000` |
 
-`serve` は自動ビルドしません。`outputDir` が無い場合は先に `npm run build -- <name>` を実行してください。
+`serve` は自動ビルドしません。`outputDir` が無い場合は先に `jskim build <name>` を実行してください。
+
+CLI の `--host` / `--port` は config より優先されます。`dev` では config hot reload 後も CLI override を再適用します。
+
+## build --all
+
+`jskim build --all` は `Object.keys(config.projects)` の定義順に全 project を順次 build します。
+
+- config は 1 回だけ load する
+- project ごとの resolve / build 失敗があっても、可能な限り次の project を続ける
+- 1 件でも失敗すれば最終 exit code は 1
+- 同一または入れ子の `outputDir` は、どの build も始める前にエラーで中断する
+- `jskim build all` は名前が `all` の project 1 件を build する（`--all` とは別）
+
+## project 名の省略
+
+設定内の project がちょうど 1 件のとき、`build` / `watch` / `serve` / `dev` で project 名を省略できます。0 件または 2 件以上では明示指定が必要です（`build --all` を除く）。
 
 ## dev.liveReload
 
@@ -335,13 +351,15 @@ files mode では出力パスの衝突を検出します。たとえば同じ `f
 | `watch` | config 変更を hot apply。`outputDir` 変更も可。以前の outputDir は自動削除しない |
 | `dev` | build / watch 関連設定を hot apply。一部 runtime 設定は再起動が必要 |
 
-`dev` では次の値が変わった candidate config は適用しません。
+`dev` では次の **effective** 値が変わった candidate config は適用しません。
 
 - `outputDir`
 - `serve.host`
 - `serve.port`
 - `dev.liveReload`
 
+CLI の `--host` / `--port` がある場合は、上書き適用後の値で比較します。そのため CLI で port を固定しているあいだに config の `serve.port` だけが変わっても、effective が同じなら再起動警告は出ません。
+
 理由: server bind と serve root を安全に切り替えるには process 再起動が必要で、部分適用すると build output と serve root がずれるためです。
 
 ## パス基準のまとめ

package/docs/create-jskim.md

@@ -24,9 +24,26 @@
 
 ```bash
 npm create jskim@latest
+pnpm create jskim
+yarn create jskim
+```
+
+代替:
+
+```bash
 npx create-jskim my-project
 ```
 
+生成完了後の案内は、実行した package manager に合わせて install / dev コマンドを表示します。検知できない実行方法では npm コマンドが表示されることがあります。
+
+生成器は dependency を自動インストールしません。案内に従って手動で install してください。
+
+既定の開発サーバー URL:
+
+```text
+http://127.0.0.1:3000/
+```
+
 ## 生成結果
 
 ```text
@@ -54,12 +71,12 @@ project/
 
 `jskim.config.js` は `files: [{ from: 'pages', to: '' }]` を使います。`.njk` は末尾の `.njk` だけを外してレンダリングし、画像などはそのままコピーします。
 
-`package.json` の scripts は bin 名 `jskim` を使います（package name ではありません）。既定の engine dependency は `@ywal123456/jskim`（`^0.4.0`）です。
+`package.json` の scripts は bin 名 `jskim` を使います（package name ではありません）。既定の engine dependency は `@ywal123456/jskim`（`^0.5.1`）です。
 
 ```json
 {
   "devDependencies": {
-    "@ywal123456/jskim": "^0.4.0"
+    "@ywal123456/jskim": "^0.5.1"
   },
   "scripts": {
     "build": "jskim build sample",
@@ -85,7 +102,7 @@ create package の `package.json` に `jskimEngine` metadata を持ち、生成
 {
   "jskimEngine": {
     "packageName": "@ywal123456/jskim",
-    "version": "^0.4.0"
+    "version": "^0.5.1"
   }
 }
 ```

package/package.json

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

package/scripts/build.js

@@ -1,11 +1,23 @@
 'use strict';
 
+const { parseCommandArgv } = require('./lib/parse-cli-args');
 const { runBuildCommand } = require('./commands/build-command');
 
+let parsed;
+try {
+  parsed = parseCommandArgv('build', process.argv.slice(2));
+} catch (err) {
+  const message = err && err.message ? err.message : String(err);
+  console.error(message);
+  process.exitCode = 1;
+  return;
+}
+
 runBuildCommand({
-  projectName: process.argv[2],
+  projectName: parsed.projectName,
+  all: parsed.options.all,
   workspaceRoot: process.cwd(),
-  usageLine: 'npm run build -- <project-name>',
+  usageLine: 'jskim build [<project>]',
 }).catch((err) => {
   const message = err && err.message ? err.message : String(err);
   console.error(message);

package/scripts/commands/build-command.js

@@ -1,11 +1,18 @@
 'use strict';
 
-const { buildProject } = require('../lib/build-project');
+const { loadConfig } = require('../lib/load-config');
+const { resolveProject } = require('../lib/resolve-project');
+const { buildProject, runBuild } = require('../lib/build-project');
+const { listProjectNames, selectProjectName } = require('../lib/select-project-name');
+const {
+  assertCompatibleOutputDirs,
+} = require('../lib/assert-output-dirs-compatible');
 
 /**
  * build コマンドを実行します。
  * @param {object} options
  * @param {string|undefined} options.projectName
+ * @param {boolean} [options.all]
  * @param {string} [options.workspaceRoot]
  * @param {string} [options.usageLine]
  * @returns {Promise<object>}
@@ -13,9 +20,24 @@ const { buildProject } = require('../lib/build-project');
 async function runBuildCommand(options = {}) {
   const workspaceRoot = options.workspaceRoot || process.cwd();
   const usageLine =
-    options.usageLine || 'npm run build -- <project-name>';
+    options.usageLine || 'jskim build [<project>]';
 
-  return buildProject(options.projectName, {
+  if (options.all) {
+    return runBuildAllProjects({
+      workspaceRoot,
+      usageLine,
+    });
+  }
+
+  const { config } = loadConfig(workspaceRoot);
+  const projectName = selectProjectName({
+    config,
+    projectName: options.projectName,
+    commandName: 'build',
+    usageLine,
+  });
+
+  return buildProject(projectName, {
     workspaceRoot,
     commandName: 'build',
     usageLine,
@@ -24,6 +46,94 @@ async function runBuildCommand(options = {}) {
   });
 }
 
+/**
+ * @param {object} options
+ * @returns {Promise<object>}
+ */
+async function runBuildAllProjects({ workspaceRoot, usageLine }) {
+  const { config } = loadConfig(workspaceRoot);
+  const names = listProjectNames(config);
+
+  if (names.length === 0) {
+    throw new Error(
+      `[JSKim] 設定にprojectがありません。\n` +
+        `jskim.config.js の projects に1件以上定義してください。\n` +
+        `使用方法: jskim build --all`
+    );
+  }
+
+  /** @type {object[]} */
+  const resolved = [];
+  /** @type {Array<{ name: string, stage: string, message: string }>} */
+  const failures = [];
+  /** @type {string[]} */
+  const successes = [];
+
+  for (const name of names) {
+    try {
+      const project = resolveProject({
+        config,
+        workspaceRoot,
+        projectName: name,
+        commandName: 'build',
+        usageLine,
+      });
+      resolved.push(project);
+    } catch (err) {
+      const message = err && err.message ? err.message : String(err);
+      failures.push({ name, stage: 'resolve', message });
+      console.error(message);
+    }
+  }
+
+  if (resolved.length > 0) {
+    assertCompatibleOutputDirs(resolved);
+  }
+
+  for (const project of resolved) {
+    console.log(`[JSKim] project "${project.name}" のbuildを開始します`);
+    try {
+      await runBuild(project, {
+        logTitle: 'ビルドが完了しました',
+        includeOutput: true,
+      });
+      successes.push(project.name);
+    } catch (err) {
+      const message = err && err.message ? err.message : String(err);
+      failures.push({ name: project.name, stage: 'build', message });
+      console.error(message);
+    }
+  }
+
+  const total = names.length;
+  const failCount = failures.length;
+  const successCount = successes.length;
+
+  console.log('');
+  console.log(
+    `[JSKim] ${total}件中${successCount}件のprojectのbuildが完了しました`
+  );
+  if (failCount > 0) {
+    console.log(`[JSKim] 失敗: ${failCount}件`);
+    for (const item of failures) {
+      console.log(`- ${item.name} (${item.stage})`);
+    }
+    const error = new Error(
+      `[JSKim] build --all が失敗しました（成功 ${successCount} / 失敗 ${failCount} / 全 ${total}）。`
+    );
+    throw error;
+  }
+
+  return {
+    total,
+    successCount,
+    failCount,
+    successes,
+    failures,
+  };
+}
+
 module.exports = {
   runBuildCommand,
+  runBuildAllProjects,
 };

package/scripts/commands/dev-command.js

@@ -9,12 +9,16 @@ const { registerShutdown } = require('./register-shutdown');
  * @param {string|undefined} options.projectName
  * @param {string} [options.workspaceRoot]
  * @param {string} [options.usageLine]
+ * @param {string} [options.host]
+ * @param {string|number} [options.port]
+ * @param {boolean} [options.open]
  * @returns {Promise<void>}
  */
 async function runDevCommand(options = {}) {
   const workspaceRoot = options.workspaceRoot || process.cwd();
   const usageLine =
-    options.usageLine || 'npm run dev -- <project-name>';
+    options.usageLine ||
+    'jskim dev [<project>] [--host <host>] [--port <port>] [--open]';
 
   const runtime = createWatchRuntime({
     mode: 'dev',
@@ -22,6 +26,11 @@ async function runDevCommand(options = {}) {
     projectName: options.projectName,
     commandName: 'dev',
     usageLine,
+    cliOverrides: {
+      host: options.host,
+      port: options.port,
+      open: Boolean(options.open),
+    },
   });
 
   let stopping = false;

package/scripts/commands/help-text.js

@@ -9,17 +9,28 @@ function getHelpText() {
     'JSKim - Nunjucksを使用した静的HTMLビルド環境',
     '',
     '使用方法:',
-    '  jskim <command> <project>',
+    '  jskim build [<project>]',
+    '  jskim build --all',
+    '  jskim watch [<project>]',
+    '  jskim serve [<project>] [--host <host>] [--port <port>]',
+    '  jskim dev [<project>] [--host <host>] [--port <port>] [--open]',
     '',
     'コマンド:',
-    '  build <project>  静的ファイルをビルドします。',
-    '  watch <project>  ファイルの変更を監視して再ビルドします。',
-    '  serve <project>  ビルド済みのファイルを配信します。',
-    '  dev <project>    ビルド・監視・サーバー・ライブリロードを起動します。',
+    '  build   静的ファイルをビルドします。',
+    '  watch   ファイルの変更を監視して再ビルドします。',
+    '  serve   ビルド済みのファイルを配信します。',
+    '  dev     ビルド・監視・サーバー・ライブリロードを起動します。',
     '',
     'オプション:',
-    '  -h, --help       ヘルプを表示します。',
-    '  -v, --version    バージョンを表示します。',
+    '  --all           設定内の全projectを順にbuildします（buildのみ）。',
+    '  --host <host>   serve / dev の待受ホストを上書きします。',
+    '  --port <port>   serve / dev の待受ポートを上書きします。',
+    '  --open          listen成功後にbrowserを1回開きます（devのみ）。',
+    '  -h, --help      ヘルプを表示します。',
+    '  -v, --version   バージョンを表示します。',
+    '',
+    '補足:',
+    '  projectを省略できるのは、設定内のprojectが1件だけの場合です。',
   ].join('\n');
 }
 
@@ -33,10 +44,11 @@ function getUnknownCommandText(command) {
     `[JSKim] 不明なコマンドです: ${command}`,
     '',
     '使用できるコマンド:',
-    '  build <project>',
-    '  watch <project>',
-    '  serve <project>',
-    '  dev <project>',
+    '  build [<project>]',
+    '  build --all',
+    '  watch [<project>]',
+    '  serve [<project>] [--host <host>] [--port <port>]',
+    '  dev [<project>] [--host <host>] [--port <port>] [--open]',
   ].join('\n');
 }
 

package/scripts/commands/serve-command.js

@@ -2,6 +2,8 @@
 
 const { loadConfig } = require('../lib/load-config');
 const { resolveProject } = require('../lib/resolve-project');
+const { selectProjectName } = require('../lib/select-project-name');
+const { applyServeCliOverrides } = require('../lib/apply-serve-cli-overrides');
 const { createStaticServer } = require('../lib/create-static-server');
 const { registerShutdown } = require('./register-shutdown');
 const { toDisplayPath } = require('./path-display');
@@ -14,24 +16,37 @@ const { assertOutputDirReady, formatListenError } = require('./serve-errors');
  * @param {string} [options.workspaceRoot]
  * @param {string} [options.usageLine]
  * @param {string} [options.buildHint]
+ * @param {string} [options.host]
+ * @param {string|number} [options.port]
  * @returns {Promise<void>}
  */
 async function runServeCommand(options = {}) {
   const workspaceRoot = options.workspaceRoot || process.cwd();
   const usageLine =
-    options.usageLine || 'npm run serve -- <project-name>';
+    options.usageLine || 'jskim serve [<project>] [--host <host>] [--port <port>]';
 
   const { config } = loadConfig(workspaceRoot);
-  const project = resolveProject({
+  const projectName = selectProjectName({
     config,
-    workspaceRoot,
     projectName: options.projectName,
     commandName: 'serve',
     usageLine,
   });
 
+  let project = resolveProject({
+    config,
+    workspaceRoot,
+    projectName,
+    commandName: 'serve',
+    usageLine,
+  });
+  project = applyServeCliOverrides(project, {
+    host: options.host,
+    port: options.port,
+  });
+
   const buildHint =
-    options.buildHint || `npm run build -- ${project.name}`;
+    options.buildHint || `jskim build ${project.name}`;
   assertOutputDirReady(project, { buildHint });
 
   const host = project.serve.host.trim();
@@ -53,6 +68,7 @@ async function runServeCommand(options = {}) {
       host,
       port,
       kind: '静的',
+      commandName: 'serve',
     });
   }
 

package/scripts/commands/serve-errors.js

@@ -10,7 +10,7 @@ const fs = require('node:fs');
  */
 function assertOutputDirReady(project, options = {}) {
   const { name, outputDir, outputDirConfig } = project;
-  const buildHint = options.buildHint || `npm run build -- ${name}`;
+  const buildHint = options.buildHint || `jskim build ${name}`;
 
   if (!outputDir || String(outputDir).trim() === '') {
     throw new Error(
@@ -44,15 +44,32 @@ function assertOutputDirReady(project, options = {}) {
   }
 }
 
-function formatListenError(err, { projectName, host, port, kind = '静的' }) {
+/**
+ * @param {Error} err
+ * @param {object} options
+ * @param {string} options.projectName
+ * @param {string} options.host
+ * @param {number} options.port
+ * @param {string} [options.kind]
+ * @param {'serve'|'dev'|string} [options.commandName]
+ */
+function formatListenError(
+  err,
+  { projectName, host, port, kind = '静的', commandName }
+) {
   const code = err && err.code;
+  const command = commandName === 'dev' ? 'dev' : 'serve';
 
   if (code === 'EADDRINUSE') {
+    const examplePort = suggestAlternatePort(port);
     return new Error(
       `[JSKim] ポート ${port} はすでに使用されています。\n` +
         `プロジェクト: ${projectName}\n` +
-        `ホスト: ${host}\n\n` +
-        `jskim.config.js の serve.port を変更してください。`
+        `ホスト: ${host}\n` +
+        `ポート: ${port}\n\n` +
+        `別のportを指定する例:\n` +
+        `jskim ${command} ${projectName} --port ${examplePort}\n\n` +
+        `または jskim.config.js の serve.port を変更してください。`
     );
   }
 
@@ -76,7 +93,16 @@ function formatListenError(err, { projectName, host, port, kind = '静的' }) {
   );
 }
 
+function suggestAlternatePort(port) {
+  const n = Number(port);
+  if (Number.isInteger(n) && n >= 1 && n < 65535) {
+    return n + 1;
+  }
+  return 3001;
+}
+
 module.exports = {
   assertOutputDirReady,
   formatListenError,
+  suggestAlternatePort,
 };