@s2j/global-npm 2.1.0 → 2.1.2

package/README.md

@@ -1,7 +1,7 @@
 # 📦 Global npm Package Setup
 
 Node.js の **グローバル npm パッケージ管理** を `package.json` で一元化する CLI です。
-macOS / Windows 11で同じ `global-npm` フローを使えます。
+macOS、Windows 11で同じ `global-npm` フローを使えます。
 
 GitHub: [stein2nd/global-npm-setup](https://github.com/stein2nd/global-npm-setup)
 
@@ -11,7 +11,7 @@ GitHub: [stein2nd/global-npm-setup](https://github.com/stein2nd/global-npm-setup
 global-npm check    # グローバルパッケージの更新確認 (ncu)
 global-npm update   # package.json のバージョン範囲を更新 (ncu -u)
 global-npm install  # dependencies を列挙して npm install -g を実行
-global-npm sync     # upstream + user-deps → 物理的なアーカイブを再生成
+global-npm sync     # upstream + user-deps → 実効 package.json を再生成
 global-npm add      # user-deps.json にパッケージを追記
 ```
 
@@ -29,16 +29,16 @@ global-npm install
 |--------|------|------|
 | Upstream 正本 | `@s2j/global-npm` 同梱 `package.json` | 公式 `dependencies` 一覧 |
 | ユーザー overlay | `$SETUP_DIR/user-deps.json` | 追加分、ピン留め |
-| 物理的なアーカイブ | `$SETUP_DIR/package.json` | ncu / install が読む実効マニフェスト |
+| 実効 package.json | `$SETUP_DIR/package.json` | ncu、install が読む実効マニフェスト |
 
 **setup ディレクトリ (`$SETUP_DIR`) のデフォルト**
 
 | OS | パス |
 |----|------|
-| macOS / Linux | `~/.config/global-npm` |
+| macOS、Linux | `~/.config/global-npm` |
 | Windows 11 | `%APPDATA%\global-npm` |
 
-`GLOBAL_NPM_SETUP_DIR` 環境変数で上書きできます。詳細は [docs/layout.md](./docs/layout.md)。
+`GLOBAL_NPM_SETUP_DIR` 環境変数で上書きできます。詳細は [docs/layout.md](./docs/layout.md) をご覧ください。
 
 ## セットアップ
 
@@ -78,14 +78,15 @@ Node.js v18以上 (LTS 推奨) が未導入の場合は、先にインストー
 
 ```sh
 npm install -g @s2j/global-npm   # CLI 本体の導入 (これは一度だけ)
+global-npm check                 # 同梱 ncu で動作 (PATH に ncu 不要)
 global-npm add @s2j/docs-linter@^1.0.16   # 任意: ユーザー追加分
-global-npm install               # 物理的なアーカイブ化 dependencies を global install
+global-npm install               # 実効 package.json の dependencies を global install
 ```
 
-初回の `global-npm install` で `~/.config/global-npm/` (Windows 11では `%APPDATA%\global-npm\`) に物理的なアーカイブ化 `package.json` が生成されます。
+初回の `global-npm install` で `~/.config/global-npm/` (Windows 11では `%APPDATA%\global-npm\`) に実効 `package.json` が生成されます。
 `global-npm install` は、`@s2j/global-npm` 自身 (自己参照) も含め、`dependencies` のキーを列挙して `npm install -g` します。
 
-### 開発 — リポジトリ clone
+### 開発: リポジトリ clone
 
 ```sh
 git clone https://github.com/stein2nd/global-npm-setup.git
@@ -110,6 +111,15 @@ global-npm sync --dry-run
 * upstream 管理パッケージのうち未 update 分は、次回 `check` 時の sync で新 range に追従する。
 * upstream パッケージをピン留めする場合は、`user-deps.json` の `dependencies` に同名で range を書く。
 
+## 使い方
+
+下記については、[使い方](./docs/usage.md) をご覧ください。
+
+* 各コマンドの役割
+* 定番フロー (`check` → `update` → `install`)
+* 毎回 `sync` を実行する必要があるか
+* upstream 管理分と追加分の衝突が起こった場合 
+
 ## 日常の更新サイクル
 
 ```mermaid
@@ -121,8 +131,8 @@ flowchart LR
 ```
 
 * **check:** sync 後に ncu で更新候補を表示。ncu 自体は range を書き換えない。
-* **update:** 物理的なアーカイブ化 `dependencies` / `devDependencies` の range を更新。
-* **install:** 物理的なアーカイブ化 **dependencies** のみ global install。
+* **update:** 実効 package.json の `dependencies`、`devDependencies` の range を更新。
+* **install:** 実効 package.json の **dependencies** のみ global install。
 
 ## 開発用 scripts
 
@@ -139,8 +149,8 @@ npm run ncu:update
 
 | v1 | v2 |
 |----|-----|
-| `~/bin/global-npm` (Zsh) | 廃止 — `npm install -g @s2j/global-npm` |
-| `install-global.zsh` | 廃止 — `global-npm install` |
+| `~/bin/global-npm` (Zsh) | 廃止: `npm install -g @s2j/global-npm` |
+| `install-global.zsh` | 廃止: `global-npm install` |
 | `ncu:install` (jq 列挙) | `global-npm install` (Node 列挙) |
 
 ### v2.0.x → v2.1
@@ -148,16 +158,16 @@ npm run ncu:update
 | v2.0.x | v2.1 |
 |--------|------|
 | setup = package root | setup = `~/.config/global-npm`。Windows は `%APPDATA%\global-npm` |
-| 同梱 `package.json` を直接 ncu | 物理的なアーカイブを ncu |
-| 3サブコマンド | 5サブコマンド (`sync` / `add` 追加) |
+| 同梱 `package.json` を直接 ncu | 実効 package.json を ncu |
+| 3サブコマンド | 5サブコマンド (`sync`、`add` 追加) |
 
 移行手順は、下記のとおりです。
 
 1. `npm update -g @s2j/global-npm` で v2.1に上げる。
 2. 追加分を `global-npm add …` で登録する。
-3. `global-npm sync` で 物理的なアーカイブを生成する。
+3. `global-npm sync` で 実効 package.json を生成する。
 4. `global-npm install` で global 環境を同期する。
 
 ## ライセンス
 
-GPL-3.0-or-later — 詳細は [LICENSE](./LICENSE) を参照してください。
+GPL-3.0-or-later: 詳細は [LICENSE](./LICENSE) をご覧ください。

package/bin/global-npm.cjs

@@ -6,6 +6,7 @@ const path = require('path');
 const { toGlobalInstallSpec } = require('../lib/install-spec.cjs');
 const { ensureSetupDir, readDependencies, readUserDeps, writeJson } = require('../lib/pkg-io.cjs');
 const { resolveSetupContext } = require('../lib/paths.cjs');
+const { resolveNcuInvocation } = require('../lib/resolve-ncu.cjs');
 const { parseAddSpec, resolveDefaultRange } = require('../lib/resolve-range.cjs');
 const { formatReport, syncManifest } = require('../lib/sync-manifest.cjs');
 
@@ -25,10 +26,10 @@ function usage() {
   process.exit(1);
 }
 
-function run(command, args) {
+function run(command, args, { useShell = shell } = {}) {
   const result = spawnSync(command, args, {
     stdio: 'inherit',
-    shell,
+    shell: useShell,
   });
 
   if (result.error) {
@@ -39,6 +40,11 @@ function run(command, args) {
   process.exit(result.status ?? 1);
 }
 
+function runNcu(args) {
+  const { command, prefixArgs, useShell } = resolveNcuInvocation(packageRoot);
+  run(command, [...prefixArgs, ...args], { useShell });
+}
+
 function prepare() {
   ensureSetupDir(ctx);
   return syncManifest(ctx);
@@ -102,19 +108,19 @@ const restArgs = process.argv.slice(3);
 switch (subcommand) {
   case 'check':
     prepare();
-    run('ncu', ['-g', '--format', 'time', '--packageFile', pkgPath]);
+    runNcu(['-g', '--format', 'time', '--packageFile', pkgPath]);
     break;
 
   case 'update':
     prepare();
-    run('ncu', ['-g', '--format', 'time', '-u', '--packageFile', pkgPath]);
+    runNcu(['-g', '--format', 'time', '-u', '--packageFile', pkgPath]);
     break;
 
   case 'install': {
     prepare();
     const dependencies = readDependencies(pkgPath);
     const specs = Object.entries(dependencies).map(([name, versionRange]) =>
-      toGlobalInstallSpec(name, versionRange),
+      toGlobalInstallSpec(name, versionRange, { pinVersion: true }),
     );
 
     if (specs.length === 0) {

package/lib/install-spec.cjs

@@ -1,13 +1,48 @@
 'use strict';
 
-function toGlobalInstallSpec(name, versionRange) {
+const { spawnSync } = require('child_process');
+
+const shell = process.platform === 'win32';
+
+function resolvePinnedVersion(name, versionRange, { spawn = spawnSync } = {}) {
+  const trimmed = typeof versionRange === 'string' ? versionRange.trim() : '';
+  if (!trimmed) {
+    return undefined;
+  }
+
+  const result = spawn('npm', ['view', `${name}@${trimmed}`, 'version', '--json'], {
+    encoding: 'utf8',
+    shell,
+  });
+
+  if (result.status !== 0) {
+    return trimmed;
+  }
+
+  try {
+    const parsed = JSON.parse(result.stdout.trim());
+    if (typeof parsed === 'string' && parsed) {
+      return parsed;
+    }
+  } catch {
+    // fall through to range fallback
+  }
+
+  return trimmed;
+}
+
+function toGlobalInstallSpec(name, versionRange, { pinVersion = false, spawn = spawnSync } = {}) {
   if (typeof versionRange === 'string' && versionRange.trim() !== '') {
-    return `${name}@${versionRange}`;
+    const target = pinVersion
+      ? resolvePinnedVersion(name, versionRange, { spawn })
+      : versionRange.trim();
+    return `${name}@${target}`;
   }
 
   return name;
 }
 
 module.exports = {
+  resolvePinnedVersion,
   toGlobalInstallSpec,
 };

package/lib/resolve-ncu.cjs

@@ -0,0 +1,62 @@
+'use strict';
+
+const { existsSync } = require('fs');
+const path = require('path');
+
+function bundledNcuCliPath(packageRoot) {
+  const nestedCli = path.join(
+    packageRoot,
+    'node_modules',
+    'npm-check-updates',
+    'build',
+    'cli.js',
+  );
+  if (existsSync(nestedCli)) {
+    return nestedCli;
+  }
+
+  try {
+    const pkgJson = require.resolve('npm-check-updates/package.json', {
+      paths: [packageRoot],
+    });
+    const cliJs = path.join(path.dirname(pkgJson), 'build', 'cli.js');
+    if (existsSync(cliJs)) {
+      return cliJs;
+    }
+  } catch {
+    // fall through to .bin / PATH
+  }
+
+  return undefined;
+}
+
+function resolveNcuInvocation(packageRoot) {
+  const cliJs = bundledNcuCliPath(packageRoot);
+  if (cliJs) {
+    return {
+      command: process.execPath,
+      prefixArgs: [cliJs],
+      useShell: false,
+    };
+  }
+
+  const binName = process.platform === 'win32' ? 'ncu.cmd' : 'ncu';
+  const localBin = path.join(packageRoot, 'node_modules', '.bin', binName);
+  if (existsSync(localBin)) {
+    return {
+      command: localBin,
+      prefixArgs: [],
+      useShell: process.platform === 'win32',
+    };
+  }
+
+  return {
+    command: 'ncu',
+    prefixArgs: [],
+    useShell: process.platform === 'win32',
+  };
+}
+
+module.exports = {
+  resolveNcuInvocation,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s2j/global-npm",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "description": "Manage globally installed npm packages via package.json with ncu.",
   "author": "Koutarou ISHIKAWA <stein2nd@gmail.com>",
   "type": "commonjs",
@@ -56,7 +56,7 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@s2j/global-npm": "^2.0.2",
+    "@s2j/global-npm": "^2.1.1",
     "corepack": "^0.35.0",
     "editorconfig-cli": "^1.0.0",
     "envinfo": "^7.21.0",