@ywal123456/jskim 0.3.1 → 0.5.0

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

@@ -5,10 +5,17 @@ const path = require('node:path');
 const chokidar = require('chokidar');
 const { loadConfig, CONFIG_FILENAME } = require('./load-config');
 const { resolveProject } = require('./resolve-project');
+const { selectProjectName } = require('./select-project-name');
+const { applyServeCliOverrides } = require('./apply-serve-cli-overrides');
 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 { classifyReload } = require('./classify-reload');
+const {
+  buildBrowserOpenUrl,
+  openBrowser: defaultOpenBrowser,
+} = require('./open-browser');
 
 const DEV_RESTART_KEYS = [
   'outputDir',
@@ -27,16 +34,24 @@ const DEV_RESTART_KEYS = [
  * @param {string|undefined} options.projectName
  * @param {string} [options.commandName]
  * @param {string} [options.usageLine]
+ * @param {{ host?: string, port?: string|number, open?: boolean }} [options.cliOverrides]
  * @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>`;
+    options.usageLine || `jskim ${commandName} [<project>]`;
+  const openBrowserFn = options.openBrowserFn || defaultOpenBrowser;
+  const cliOverrides = {
+    host: options.cliOverrides && options.cliOverrides.host,
+    port: options.cliOverrides && options.cliOverrides.port,
+    open: Boolean(options.cliOverrides && options.cliOverrides.open),
+  };
 
+  /** @type {string|undefined} */
+  let selectedProjectName = options.projectName;
   let currentProject = null;
   let configPath = null;
   let projectWatcher = null;
@@ -44,6 +59,7 @@ function createWatchRuntime(options) {
   let liveReload = null;
   let staticServer = null;
   let liveReloadEnabled = false;
+  let browserOpened = false;
 
   let stopping = false;
   let started = false;
@@ -52,15 +68,31 @@ function createWatchRuntime(options) {
   let pendingConfigReload = false;
   let sourceBuilding = false;
 
+  function withCliOverrides(project) {
+    return applyServeCliOverrides(project, {
+      host: cliOverrides.host,
+      port: cliOverrides.port,
+    });
+  }
+
   function resolveCurrentProject() {
     const loaded = loadConfig(workspaceRoot);
-    const project = resolveProject({
+    const name = selectProjectName({
       config: loaded.config,
-      workspaceRoot,
-      projectName,
+      projectName: selectedProjectName,
       commandName,
       usageLine,
     });
+    selectedProjectName = name;
+    const project = withCliOverrides(
+      resolveProject({
+        config: loaded.config,
+        workspaceRoot,
+        projectName: name,
+        commandName,
+        usageLine,
+      })
+    );
     return {
       project,
       configPath: loaded.configPath,
@@ -77,13 +109,15 @@ function createWatchRuntime(options) {
     currentProject = resolved.project;
     configPath = resolved.configPath;
 
+    // ready ログより先に config 監視を開始する。
+    // そうしないと「監視しています」直後の config 変更を見逃すことがある。
+    beginConfigWatching();
+
     if (mode === 'dev') {
       await startDevSession(currentProject, { initial: true });
     } else {
       await startWatchSession(currentProject, { initial: true });
     }
-
-    beginConfigWatching();
   }
 
   async function startWatchSession(project, { initial }) {
@@ -115,6 +149,7 @@ function createWatchRuntime(options) {
     const host = project.serve.host.trim();
     const port = project.serve.port;
     const outputDisplay = toDisplayPath(project.outputDir, workspaceRoot);
+    const browserUrl = buildBrowserOpenUrl({ host, port });
 
     liveReload = createLiveReload({
       projectName: project.name,
@@ -151,6 +186,7 @@ function createWatchRuntime(options) {
         host,
         port,
         kind: '開発',
+        commandName: 'dev',
       });
       await cleanupDevComponents();
       throw formatted;
@@ -162,11 +198,30 @@ function createWatchRuntime(options) {
       console.log('[JSKim] 開発サーバーを起動しました。');
       console.log(`プロジェクト: ${project.name}`);
       console.log(`ルート: ${outputDisplay}`);
-      console.log(`URL: ${staticServer.url}`);
+      console.log(`URL: ${browserUrl}`);
       console.log(
         `ライブリロード: ${liveReloadEnabled ? '有効' : '無効'}`
       );
       console.log('終了するには Ctrl+C を押してください。');
+      maybeOpenBrowser(browserUrl);
+    }
+  }
+
+  function maybeOpenBrowser(url) {
+    if (!cliOverrides.open || browserOpened || stopping) {
+      return;
+    }
+    browserOpened = true;
+    const result = openBrowserFn(url);
+    if (!result.ok) {
+      const message =
+        result.error && result.error.message
+          ? result.error.message
+          : String(result.error || 'unknown');
+      console.warn(
+        `[JSKim] browserを開けませんでした。手動で次のURLを開いてください: ${url}\n` +
+          `原因: ${message}`
+      );
     }
   }
 
@@ -185,10 +240,28 @@ function createWatchRuntime(options) {
   }
 
   function wireDevSourceReload(watcher) {
-    watcher.on('build:success', ({ initial }) => {
-      if (!initial && liveReloadEnabled && liveReload) {
-        liveReload.broadcastReload();
+    watcher.on('build:success', ({ initial, events }) => {
+      if (initial || !liveReloadEnabled || !liveReload) {
+        return;
+      }
+      // 未解決の config error がある間は source 成功で overlay/reload しない
+      if (liveReload.hasConfigError()) {
+        return;
+      }
+      const kind = classifyReload({
+        events,
+        sourceDir: currentProject && currentProject.sourceDir,
+        templates: currentProject && currentProject.templates,
+      });
+      liveReload.notifySourceBuildSuccess(kind);
+    });
+
+    watcher.on('build:failure', ({ error }) => {
+      if (!liveReloadEnabled || !liveReload) {
+        return;
       }
+      // Error.message は完成済みの診断文字列を再利用する
+      liveReload.broadcastBuildError(error);
     });
   }
 
@@ -293,21 +366,38 @@ function createWatchRuntime(options) {
     let candidate;
     try {
       const loaded = loadConfig(workspaceRoot);
-      candidate = resolveProject({
+      const name = selectProjectName({
         config: loaded.config,
-        workspaceRoot,
-        projectName,
+        projectName: selectedProjectName,
         commandName,
         usageLine,
       });
+      selectedProjectName = name;
+      candidate = withCliOverrides(
+        resolveProject({
+          config: loaded.config,
+          workspaceRoot,
+          projectName: name,
+          commandName,
+          usageLine,
+        })
+      );
     } catch (err) {
       const message = err && err.message ? err.message : String(err);
       console.error('[JSKim] 設定ファイルの再読み込みに失敗しました。');
       console.error(message);
       console.error('[JSKim] 以前の正常な設定を継続します。');
+      if (mode === 'dev' && liveReloadEnabled && liveReload) {
+        liveReload.broadcastConfigError(message);
+      }
       return;
     }
 
+    // candidate は validation 済み。以降の失敗は build error として扱う
+    if (mode === 'dev' && liveReloadEnabled && liveReload) {
+      liveReload.clearConfigError();
+    }
+
     if (mode === 'dev') {
       const restartKeys = getRestartRequiredChanges(currentProject, candidate);
       if (restartKeys.length > 0) {
@@ -348,6 +438,9 @@ function createWatchRuntime(options) {
       console.error('[JSKim] 設定の再読み込み後に監視の更新に失敗しました。');
       console.error(message);
       console.error('[JSKim] 以前の正常な設定を継続します。');
+      if (mode === 'dev' && liveReloadEnabled && liveReload) {
+        liveReload.broadcastConfigError(message);
+      }
       return;
     }
 
@@ -388,9 +481,9 @@ function createWatchRuntime(options) {
         hooks.onInitialBuildSuccess();
       }
     };
-    const onFailure = ({ initial }) => {
+    const onFailure = ({ initial, error }) => {
       if (initial && hooks.onInitialBuildFailure) {
-        hooks.onInitialBuildFailure();
+        hooks.onInitialBuildFailure(error);
       }
     };
     projectWatcher.on('build:success', onSuccess);

package/scripts/lib/open-browser.js

@@ -0,0 +1,102 @@
+'use strict';
+
+const { spawn } = require('node:child_process');
+
+/**
+ * browser で開く URL を組み立てます（listen host と分離）。
+ *
+ * @param {{ host: string, port: number }} options
+ * @returns {string}
+ */
+function buildBrowserOpenUrl({ host, port }) {
+  let browserHost = String(host || '').trim();
+  if (browserHost === '0.0.0.0') {
+    browserHost = '127.0.0.1';
+  } else if (browserHost === '::') {
+    browserHost = 'localhost';
+  }
+
+  const portText = String(port);
+  if (browserHost.includes(':') && !browserHost.startsWith('[')) {
+    return `http://[${browserHost}]:${portText}/`;
+  }
+  return `http://${browserHost}:${portText}/`;
+}
+
+/**
+ * OS別の open 用 executable / args を返します（shell 不使用）。
+ *
+ * @param {string} url
+ * @param {string} [platform=process.platform]
+ * @returns {{ command: string, args: string[] }}
+ */
+function buildOpenBrowserCommand(url, platform = process.platform) {
+  if (typeof url !== 'string' || url.trim() === '') {
+    throw new Error('[JSKim] browser URLが空です。');
+  }
+
+  if (platform === 'win32') {
+    return {
+      command: 'rundll32.exe',
+      args: ['url.dll,FileProtocolHandler', url],
+    };
+  }
+
+  if (platform === 'darwin') {
+    return {
+      command: 'open',
+      args: [url],
+    };
+  }
+
+  return {
+    command: 'xdg-open',
+    args: [url],
+  };
+}
+
+/**
+ * browser を開きます。失敗しても throw せず結果を返します。
+ *
+ * @param {string} url
+ * @param {object} [options]
+ * @param {typeof spawn} [options.spawnFn]
+ * @param {string} [options.platform]
+ * @returns {{ ok: boolean, error?: Error, command: string, args: string[] }}
+ */
+function openBrowser(url, options = {}) {
+  const spawnFn = options.spawnFn || spawn;
+  const platform = options.platform || process.platform;
+  const { command, args } = buildOpenBrowserCommand(url, platform);
+
+  try {
+    const child = spawnFn(command, args, {
+      shell: false,
+      stdio: 'ignore',
+      detached: true,
+      windowsHide: true,
+    });
+    if (child && typeof child.unref === 'function') {
+      child.unref();
+    }
+    if (child && typeof child.on === 'function') {
+      child.on('error', () => {
+        // warning は呼び出し側で扱う
+      });
+    }
+    return { ok: true, command, args };
+  } catch (err) {
+    return {
+      ok: false,
+      error: err instanceof Error ? err : new Error(String(err)),
+      command,
+      args,
+    };
+  }
+}
+
+module.exports = {
+  buildBrowserOpenUrl,
+  buildOpenBrowserCommand,
+  openBrowser,
+};

package/scripts/lib/parse-cli-args.js

@@ -0,0 +1,216 @@
+'use strict';
+
+const COMMANDS = new Set(['build', 'watch', 'serve', 'dev']);
+
+const COMMAND_OPTIONS = {
+  build: new Set(['--all']),
+  watch: new Set([]),
+  serve: new Set(['--host', '--port']),
+  dev: new Set(['--host', '--port', '--open']),
+};
+
+const VALUE_OPTIONS = new Set(['--host', '--port']);
+const BOOLEAN_OPTIONS = new Set(['--all', '--open']);
+
+/**
+ * jskim の argv（node / script を除く）を解析します。
+ *
+ * @param {string[]} argv
+ * @returns {{
+ *   kind: 'help'|'version'|'command',
+ *   command?: string,
+ *   projectName?: string,
+ *   options: { all: boolean, open: boolean, host?: string, port?: string }
+ * }}
+ */
+function parseJskimArgv(argv) {
+  const args = Array.isArray(argv) ? argv.slice() : [];
+
+  if (args.length === 0) {
+    return { kind: 'help', options: emptyOptions() };
+  }
+
+  const first = args[0];
+  if (first === '--help' || first === '-h' || first === 'help') {
+    return { kind: 'help', options: emptyOptions() };
+  }
+  if (first === '--version' || first === '-v') {
+    return { kind: 'version', options: emptyOptions() };
+  }
+
+  if (!COMMANDS.has(first)) {
+    throw new Error(formatUnknownCommand(first));
+  }
+
+  const parsed = parseCommandArgv(first, args.slice(1));
+  return {
+    kind: 'command',
+    command: first,
+    projectName: parsed.projectName,
+    options: parsed.options,
+  };
+}
+
+/**
+ * 特定 command の残 argv を解析します（scripts/*.js 用）。
+ *
+ * @param {string} command
+ * @param {string[]} argv command 名を除いた引数、または scripts の process.argv.slice(2)
+ * @returns {{ projectName?: string, options: object }}
+ */
+function parseCommandArgv(command, argv) {
+  if (!COMMANDS.has(command)) {
+    throw new Error(formatUnknownCommand(command));
+  }
+
+  const allowed = COMMAND_OPTIONS[command];
+  const args = Array.isArray(argv) ? argv.slice() : [];
+  const options = emptyOptions();
+  /** @type {string[]} */
+  const positionals = [];
+  /** @type {Set<string>} */
+  const seen = new Set();
+
+  for (let i = 0; i < args.length; i += 1) {
+    const token = args[i];
+
+    if (token === '--') {
+      throw new Error(
+        `[JSKim] サポートされていない引数です: --\n` +
+          `使用方法: jskim ${command} ...`
+      );
+    }
+
+    if (token.startsWith('-')) {
+      if (token.includes('=') && token.startsWith('--')) {
+        throw new Error(
+          `[JSKim] この書き方のoptionはサポートしていません: ${token}\n` +
+            `例: --port 4000（= は使えません）`
+        );
+      }
+
+      if (!BOOLEAN_OPTIONS.has(token) && !VALUE_OPTIONS.has(token)) {
+        throw new Error(
+          `[JSKim] 不明なoptionです: ${token}\n` +
+            formatAllowedOptions(command)
+        );
+      }
+
+      if (!allowed.has(token)) {
+        throw new Error(
+          `[JSKim] コマンド "${command}" ではoption ${token} を使えません。\n` +
+            formatAllowedOptions(command)
+        );
+      }
+
+      if (seen.has(token)) {
+        throw new Error(`[JSKim] optionが重複しています: ${token}`);
+      }
+      seen.add(token);
+
+      if (BOOLEAN_OPTIONS.has(token)) {
+        if (token === '--all') {
+          options.all = true;
+        } else if (token === '--open') {
+          options.open = true;
+        }
+        continue;
+      }
+
+      // value option
+      const value = args[i + 1];
+      if (
+        value === undefined ||
+        (value.startsWith('-') && isKnownOptionToken(value))
+      ) {
+        throw new Error(
+          `[JSKim] option ${token} の値がありません。\n` +
+            `使用方法: ${token} <value>`
+        );
+      }
+      i += 1;
+      if (token === '--host') {
+        options.host = value;
+      } else if (token === '--port') {
+        options.port = value;
+      }
+      continue;
+    }
+
+    positionals.push(token);
+  }
+
+  if (positionals.length > 1) {
+    throw new Error(
+      `[JSKim] project名は1つだけ指定してください。\n` +
+        `受け取った値: ${positionals.join(', ')}\n` +
+        `使用方法: jskim ${command} [<project>]`
+    );
+  }
+
+  if (options.all && positionals.length > 0) {
+    throw new Error(
+      `[JSKim] --all と project名は同時に指定できません。\n` +
+        `使用方法: jskim build --all\n` +
+        `または: jskim build <project>`
+    );
+  }
+
+  if (options.all && command !== 'build') {
+    throw new Error(
+      `[JSKim] コマンド "${command}" ではoption --all を使えません。\n` +
+        formatAllowedOptions(command)
+    );
+  }
+
+  return {
+    projectName: positionals[0],
+    options,
+  };
+}
+
+function emptyOptions() {
+  return {
+    all: false,
+    open: false,
+  };
+}
+
+function isKnownOptionToken(token) {
+  return (
+    BOOLEAN_OPTIONS.has(token) ||
+    VALUE_OPTIONS.has(token) ||
+    token === '--help' ||
+    token === '-h' ||
+    token === '--version' ||
+    token === '-v'
+  );
+}
+
+function formatAllowedOptions(command) {
+  const allowed = [...COMMAND_OPTIONS[command]];
+  if (allowed.length === 0) {
+    return `コマンド "${command}" で使える追加optionはありません。`;
+  }
+  return `使えるoption: ${allowed.join(', ')}`;
+}
+
+function formatUnknownCommand(command) {
+  return [
+    `[JSKim] 不明なコマンドです: ${command}`,
+    '',
+    '使用できるコマンド:',
+    '  build [<project>]',
+    '  build --all',
+    '  watch [<project>]',
+    '  serve [<project>] [--host <host>] [--port <port>]',
+    '  dev [<project>] [--host <host>] [--port <port>] [--open]',
+  ].join('\n');
+}
+
+module.exports = {
+  parseJskimArgv,
+  parseCommandArgv,
+  COMMANDS,
+  COMMAND_OPTIONS,
+};

package/scripts/lib/select-project-name.js

@@ -0,0 +1,64 @@
+'use strict';
+
+/**
+ * config.projects のキーを定義順で返します。
+ * @param {object} config
+ * @returns {string[]}
+ */
+function listProjectNames(config) {
+  const projects = config && config.projects;
+  if (!projects || typeof projects !== 'object') {
+    return [];
+  }
+  return Object.keys(projects);
+}
+
+/**
+ * positional project が無い場合の自動選択、または明示名を返します。
+ *
+ * @param {object} options
+ * @param {object} options.config
+ * @param {string|undefined} options.projectName
+ * @param {string} [options.commandName]
+ * @param {string} [options.usageLine]
+ * @returns {string}
+ */
+function selectProjectName({
+  config,
+  projectName,
+  commandName = 'build',
+  usageLine,
+}) {
+  const names = listProjectNames(config);
+  const usage =
+    usageLine || `jskim ${commandName} [<project>]`;
+
+  if (projectName && String(projectName).trim() !== '') {
+    return String(projectName).trim();
+  }
+
+  if (names.length === 0) {
+    throw new Error(
+      `[JSKim] 設定にprojectがありません。\n` +
+        `jskim.config.js の projects に1件以上定義してください。\n` +
+        `使用方法: ${usage}`
+    );
+  }
+
+  if (names.length === 1) {
+    return names[0];
+  }
+
+  const list = names.map((name) => `- ${name}`).join('\n');
+  throw new Error(
+    `[JSKim] projectを指定してください。\n` +
+      `使用方法: ${usage}\n\n` +
+      `利用可能なproject:\n` +
+      list
+  );
+}
+
+module.exports = {
+  listProjectNames,
+  selectProjectName,
+};

package/scripts/lib/stylesheet-reload.js

@@ -0,0 +1,58 @@
+'use strict';
+
+const CSS_CACHE_PARAM = '_jskim';
+
+/**
+ * same-origin の stylesheet URL かどうかを判定します。
+ * browser runtime へ Function#toString で埋め込むため、外部クロージャに依存しません。
+ *
+ * @param {string} href
+ * @param {string} pageOrigin location.origin または location.href
+ * @returns {boolean}
+ */
+function isSameOriginStylesheetHref(href, pageOrigin) {
+  if (!href || typeof href !== 'string') {
+    return false;
+  }
+  const trimmed = href.trim();
+  if (!trimmed || trimmed.startsWith('data:')) {
+    return false;
+  }
+
+  try {
+    const resolved = new URL(trimmed, pageOrigin);
+    const origin = new URL(pageOrigin);
+    return resolved.origin === origin.origin;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * cache-busting query を付与または更新します。hash と他 query は維持します。
+ * browser runtime へ Function#toString で埋め込むため、パラメータ名はリテラルです。
+ *
+ * @param {string} href
+ * @param {string} pageOrigin
+ * @param {string|number} token
+ * @returns {string|null}
+ */
+function appendCacheBustParam(href, pageOrigin, token) {
+  if (!isSameOriginStylesheetHref(href, pageOrigin)) {
+    return null;
+  }
+
+  try {
+    const url = new URL(href, pageOrigin);
+    url.searchParams.set('_jskim', String(token));
+    return `${url.pathname}${url.search}${url.hash}`;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  CSS_CACHE_PARAM,
+  isSameOriginStylesheetHref,
+  appendCacheBustParam,
+};