@nuwel-dev/setup 1.0.1 → 1.0.3

package/README.md

@@ -10,13 +10,50 @@ npx @nuwel-dev/setup
 > この橋自身は公開 npm 側に在るため scope registry を明示して実行する:
 > `npx --@nuwel-dev:registry=https://registry.npmjs.org @nuwel-dev/setup`
 
+## 動作環境（**始める前に**）
+
+| | 要件 | 満たさない時 |
+|---|---|---|
+| OS | **macOS / Linux**（Windows は WSL2 の Linux 側で） | トークンを尋ねる**前**に停止します |
+| Node | **22.18 以上 / 24.11 以上 / 26 以上**（23・25 は不可） | 同上（`nvm` / `Volta` で切り替えてから再実行） |
+
+どちらもウィザードの起動直後に検査します。**発行済みのトークンが宙に浮かないよう、
+秘密を尋ねる前に落とす**設計です（旧版は `.npmrc` を書き終えた最後の 1 手で英語のエラーになりました）。
+
 ## これは何をするか
 
-1. GitHub のトークン作成ページ URL を表示する（`read:packages` にチェック済みの URL）
-2. 貼り付けられたトークンを受け取る（**画面には表示しない**）
-3. `~/.npmrc` にスコープ行と authToken を書く（権限 **600**・他の行は壊さない）
-4. 接続確認して、401 / 403 / 404 を**平語**で説明する（「招待をまだ Accept していない」等）
-5. `npx @nuwel-dev/figma-kit init` へ委譲する
+1. 前提（OS / Node 版・`~/.npmrc` に安全に置けるか）を検査する — 満たさなければここで停止
+2. GitHub のトークン作成ページ URL を表示する（`read:packages` にチェック済みの URL）
+3. 貼り付けられたトークンを受け取る（**画面には表示しない**）
+4. **先に接続確認する**（`~/.npmrc` はまだ触りません）。401 / 403 / 404 を**平語**で説明します（「招待をまだ Accept していない」等）
+5. **通った時だけ** `~/.npmrc` にスコープ行と authToken を書く（権限 **600**・他の行は壊さない・原子的に置き換え）
+6. `@nuwel-dev/figma-kit` の **latest を解決してメジャー（1）を検査し、その正確な版**で `init` へ委譲する（`^1` のようなレンジは prerelease〈1.4.0-alpha.x〉に一致しないため使いません）
+
+> **失敗しても `~/.npmrc` は 1 バイトも変わりません。** 順序が 4 → 5 なのはそのためです。
+> 誤入力・期限切れ・権限不足のトークンを 1 回貼っただけで、それまで動いていた**別のトークン**
+> （`//npm.pkg.github.com/:_authToken`）が消えては困るからです。書き込みは新しいファイルを作って
+> `rename` で置き換えるので、「途中まで書けた壊れた `.npmrc`」も残りません。
+
+### 接続確認の経路（企業 proxy 下でも止まらないように）
+
+第一手は **`npm` そのもの**（`npm view @nuwel-dev/figma-kit version --registry=https://npm.pkg.github.com`）です。
+キットを実際に落とすのも `npm` なので、`~/.npmrc` の `proxy` / `https-proxy` / `cafile` / `strict-ssl` が
+そのまま効きます。トークンは **`npm` の引数には渡さず環境変数だけ**で渡します（引数は同じマシンの
+他のユーザーから `ps` で読めるため）。問い合わせ先はコマンドラインで固定するので、`~/.npmrc` に
+古い `@nuwel-dev:registry=` が残っていても、そちらへ問い合わせて「接続できました」と誤表示することは
+ありません。
+
+`npm` が無い・時間内に終わらない・HTTP として判定できない場合だけ、直接 HTTPS で確かめます（その旨を表示）。
+**どちらか一方でも通れば合格**にします — proxy 下は `npm` だけが通り、配布物が prerelease だけの時は
+直接接続だけが通るので、片方の失敗で買い手を止めないためです。
+
+### 残っているリスク（正直に）
+
+版は固定しますが、**受け取った tarball が発行元の物かの検証はローカルでは行っていません**
+（`npm` が lockfile の integrity で tarball のハッシュは検証しますが、それは「レジストリが返した物と
+lockfile が一致する」ことであって「発行元が出した物である」ことではありません）。
+発行元の同一性は、`figma-kit diagnose` の「配布物同一性」が出す **pkg-merkle** を、
+リリース告知に載る値と照合して確認してください。
 
 ## なぜ公開 npm にあるのか
 
@@ -31,12 +68,18 @@ publish は provenance 付き（公開レジストリでのみ効く）。
 - 書き込み先は `~/.npmrc` だけ。案件ディレクトリの `.npmrc` には**スコープ行しか書かない**（`figma-kit init` が書く・`.gitignore` 済み）
 - stdout・ログ・エラーメッセージにトークンを出す経路を持たない（表示は `redact()` のマスクのみ）
 - 例外は種別（`e.code`）だけを表示する（例外メッセージにトークンが載る事故を構造で防ぐ）
+- 子プロセス（接続確認の `npm`）へは**環境変数だけ**で渡す。コマンドライン引数には載せません
+- **接続確認に失敗したら `~/.npmrc` は一切変更しません**（成功した時だけ、新しいファイルを作って `rename` で原子的に置き換えます）
+
+**マスク表示の仕様**: 登録の成功行に `abcd…yz（40 文字）` の形で **先頭 4 文字・末尾 2 文字・全体の文字数**だけを
+表示します（それ以外は 1 文字も出しません）。これは「貼り付けが途中で切れていないか」「別の値を貼っていないか」を
+買い手が自分で確かめられるようにするためで、意図的な仕様です。全部を隠すと、失敗時に何が起きたか誰も分かりません。
 
 ## 非対話フラグ（テスト・CI 用）
 
 | flag | 意味 |
 |---|---|
-| `--no-verify` | 接続確認を行わない |
+| `--no-verify` | 接続確認を行わない（**確認せずに書く**唯一の経路。ネットワークが無い環境での明示指定） |
 | `--no-init` | `figma-kit init` へ委譲しない |
 | `--home=<dir>` | `~/.npmrc` の代わりに `<dir>/.npmrc` を書く |
 | `--dir=<dir>` | init を実行する案件ディレクトリ（既定は cwd） |

package/bin/setup.js

@@ -8,10 +8,16 @@
  * なぜ公開 npm に置くのか: キット本体 `@nuwel-dev/figma-kit` は GitHub Packages（private）にあり、
  * **トークンを設定しないと落とせない**。その設定手順自体を private 側に置くと鶏と卵になる。
  * ここは秘密を 1 バイトも含まず（依存もゼロ）、やることは 4 つだけ:
- *   ① トークン作成ページの URL を出す → ② 貼ってもらう → ③ ~/.npmrc へ 0600 で書く →
- *   ④ 接続確認（401/404 を平語で説明）→ ⑤ `npx @nuwel-dev/figma-kit init` へ委譲
+ *   ① トークン作成ページの URL を出す → ② 貼ってもらう → ③ **接続確認**（401/404 を平語で説明）→
+ *   ④ **通った時だけ** ~/.npmrc へ 0600 で原子的に書く → ⑤ `npx @nuwel-dev/figma-kit init` へ委譲
+ *
+ * **③ が ④ より先なのは仕様**（2026-08-26・codex R2 Q7 block）: 旧版は貼られた直後に `~/.npmrc` の
+ * スコープ行と authToken 行を置換し、その後で接続確認していた。誤入力 1 回で、それまで動いていた
+ * 別トークンが不可逆に消える（＝買い手の既存の私有パッケージ取得を購入初日に壊す）。
+ * 接続確認は**買い手が実際に取得に使う npm CLI 経由**を第一手にする（企業 proxy・社内 CA を通す）。
  *
  * **トークンは stdout・ログ・エラー文へ 1 度も出さない**（表示は lib/wizard.js の redact のみ）。
+ * npm へ渡す時も **argv には載せず env だけ**（argv は同一ホストの他ユーザーから `ps` で読める）。
  *
  * flags（テスト・非対話用）:
  *   --no-verify   接続確認を行わない（ネットワークが無い環境）
@@ -57,8 +63,9 @@ function prompt(question) {
   });
 }
 
-/** GitHub Packages に GET して権限を確かめる（応答本文は読み捨て・トークンはヘッダのみ） */
-function probe(token) {
+/** GitHub Packages に直接 GET して権限を確かめる（応答本文は読み捨て・トークンはヘッダのみ）。
+ *  **npm 経路で判定が付かなかった時だけ**使うフォールバック（npm の proxy / 証明書設定を通らないため） */
+function probeDirect(token) {
   return new Promise((resolve) => {
     // eslint-disable-next-line global-require
     const https = require('https');
@@ -72,20 +79,39 @@ function probe(token) {
   });
 }
 
-function writeNpmrc(token) {
-  // 秘密を書く時の順序（codex R1〜R3 block の封鎖）:
-  //   ① 親ディレクトリが自分の所有で他者書込み不可（差し替え主体を排除）。O_NOFOLLOW / getuid が無い OS は**書かない**
-  //   ② 既存 .npmrc は O_NOFOLLOW で開き **fd に対して** fstat（通常ファイル・自分の所有・nlink 1）してから内容を読む
-  //   ③ **既存 inode には書かない**（他者が先に read fd を握っていれば chmod 後も読める・codex R3）:
-  //      同ディレクトリに O_EXCL|0600 で新 inode を作り → 書く → fsync → rename で置き換える（atomic）
+/**
+ * npm CLI 経由の接続確認（**買い手が実際に取得に使う経路そのもの**＝proxy・cafile・strict-ssl が効く）。
+ * トークンは argv に 1 度も載せず env だけで渡す（`W.npmProbeEnv` が唯一の口）。stdin は閉じる
+ * （ここまでに読み終えた stdin を npm に食わせない）。
+ */
+function probeNpm(token) {
+  const r = spawnSync('npm', W.npmProbeArgs(), {
+    encoding: 'utf8', env: W.npmProbeEnv(process.env, token),
+    stdio: ['ignore', 'pipe', 'pipe'], timeout: 30000,
+  });
+  return W.classifyNpmProbe({
+    status: r.status,
+    output: `${r.stdout || ''}${r.stderr || ''}`,
+    spawnError: r.error ? (r.error.code || 'ESPAWN') : null,
+  });
+}
+
+/**
+ * `~/.npmrc` に**安全に書けるか**を検査し、既存の中身を返す。**1 バイトも書かない**ので
+ * 「トークンを尋ねる前の前提確認」と「書く直前の再検査（TOCTOU）」の両方から呼べる。
+ *
+ * 秘密を書く時の順序（codex R1〜R3 block の封鎖）:
+ *   ① 親ディレクトリが自分の所有で他者書込み不可（差し替え主体を排除）。O_NOFOLLOW / getuid が無い OS は**書かない**
+ *   ② 既存 .npmrc は O_NOFOLLOW で開き **fd に対して** fstat（通常ファイル・自分の所有・nlink 1）してから内容を読む
+ */
+function inspectNpmrc() {
   const dir = path.dirname(NPMRC);
   fs.mkdirSync(dir, { recursive: true });
   if (typeof process.getuid !== 'function' || !fs.constants.O_NOFOLLOW) throw Object.assign(new Error('unsafe-platform'), { code: 'EPLATFORM' });
   const uid = process.getuid();
   const dst = fs.lstatSync(dir);
   if (!dst.isDirectory() || dst.uid !== uid || (dst.mode & 0o022)) throw Object.assign(new Error('parent-dir'), { code: 'EPARENT' });
-  const { O_RDONLY, O_WRONLY, O_CREAT, O_EXCL, O_NOFOLLOW } = fs.constants;
-  // ② 既存内容（あれば）
+  const { O_RDONLY, O_NOFOLLOW } = fs.constants;
   let existing = '';
   let rfd = null;
   try { rfd = fs.openSync(NPMRC, O_RDONLY | O_NOFOLLOW); }
@@ -101,7 +127,19 @@ function writeNpmrc(token) {
       existing = fs.readFileSync(rfd, 'utf8');
     } finally { fs.closeSync(rfd); }
   }
-  // ③ 新 inode に書いて rename
+  return existing;
+}
+
+/**
+ * `~/.npmrc` を置き換える。**`W.mayWriteNpmrc` が ok を返した後にだけ呼ぶ**（codex R2 Q7 block）。
+ * ③ **既存 inode には書かない**（他者が先に read fd を握っていれば chmod 後も読める・codex R3）:
+ *    同ディレクトリに O_EXCL|0600 で新 inode を作り → 書く → fsync → rename で置き換える（atomic）。
+ *    rename まで到達しなければ既存の `.npmrc` は無傷＝「途中まで書けた壊れた .npmrc」を作らない。
+ */
+function writeNpmrc(token) {
+  const existing = inspectNpmrc(); // 書く直前にもう一度（前提確認からここまでに差し替えられていないか）
+  const dir = path.dirname(NPMRC);
+  const { O_WRONLY, O_CREAT, O_EXCL, O_NOFOLLOW } = fs.constants;
   const tmp = path.join(dir, `.npmrc.${process.pid}.${Date.now()}.tmp`);
   const wfd = fs.openSync(tmp, O_WRONLY | O_CREAT | O_EXCL | O_NOFOLLOW, 0o600);
   try {
@@ -115,10 +153,37 @@ function writeNpmrc(token) {
   try { fs.renameSync(tmp, NPMRC); } catch (e) { try { fs.unlinkSync(tmp); } catch (_) { /* noop */ } throw e; }
 }
 
+/** `.npmrc` 系の例外を買い手向けの 1 行にする。**例外の message は使わない**（トークンが載る経路を作らない） */
+function npmrcErrorMessage(e) {
+  const code = e && e.code;
+  if (code === 'ESYMLINK') return `${NPMRC} がシンボリックリンクです。トークンをリンク先へ書くのは危険なので中止しました。リンクを外してから再実行してください`;
+  if (code === 'ENOTFILE') return `${NPMRC} が通常ファイルではありません。確認してから再実行してください`;
+  if (code === 'EOWNER') return `${NPMRC} があなたの所有でないか、ハードリンクされています。確認してから再実行してください`;
+  if (code === 'EPARENT') return `${path.dirname(NPMRC)} があなたの所有でないか、他のユーザーが書き込めます（安全にトークンを置けません）。権限を直してから再実行してください`;
+  if (code === 'EPLATFORM') return 'この OS では安全にトークンを保存できません（macOS / Linux で実行してください）';
+  return `${NPMRC} に書けませんでした（${code || 'エラー'}）。ホームディレクトリの権限を確認してください`;
+}
+
 (async () => {
   say('');
   say('=== figma-kit セットアップ ===');
   say('');
+  // **秘密を尋ねる前**に前提を検査する（L6#1 / L1#15）。旧版は PAT を貼らせ切ってから
+  // EBADENGINE（Node 版）・EPLATFORM（Windows）で落ちており、発行済みトークンが宙に浮いた。
+  {
+    // eslint-disable-next-line global-require
+    const engines = (require('../package.json').engines || {}).node || '';
+    const nv = W.nodeSupported(process.versions.node, engines);
+    if (!nv.ok) { say(`❌ ${nv.message}`); process.exit(1); }
+    const pv = W.platformSupported({ getuid: process.getuid, hasNoFollow: !!fs.constants.O_NOFOLLOW });
+    if (!pv.ok) { say(`❌ ${pv.message}`); process.exit(1); }
+    // `~/.npmrc` に**安全に置けるか**もここで見る（1 バイトも書かない検査）。旧版は書き込み時に初めて
+    // symlink / 所有者を判定していたため、買い手は PAT を発行して貼った**後**に「中止しました」と言われ、
+    // 発行済みトークンが宙に浮いた（L1#15 と同型）。書く直前の再検査は writeNpmrc 側に残す（TOCTOU）。
+    try { inspectNpmrc(); } catch (e) { say(`❌ ${npmrcErrorMessage(e)}`); process.exit(1); }
+    say(`· 前提の確認 OK（Node v${process.versions.node} / ${process.platform}）`);
+    say('');
+  }
   say('キット本体は GitHub の限定配布（あなたのアカウント＝1 席）です。');
   say('取得用のトークンを 1 回だけ登録します。所要 2 分。');
   say('');
@@ -132,29 +197,31 @@ function writeNpmrc(token) {
   if (!shape.ok) { say(`\n❌ ${shape.message}`); process.exit(1); }
   const token = shape.token;
 
-  try { writeNpmrc(token); } catch (e) {
-    // エラー文にトークンが載る経路を作らない（メッセージは自前で組む）
-    if (e.code === 'ESYMLINK') say(`\n❌ ${NPMRC} がシンボリックリンクです。トークンをリンク先へ書くのは危険なので中止しました。リンクを外してから再実行してください`);
-    else if (e.code === 'ENOTFILE') say(`\n❌ ${NPMRC} が通常ファイルではありません。確認してから再実行してください`);
-    else if (e.code === 'EOWNER') say(`\n❌ ${NPMRC} があなたの所有でないか、ハードリンクされています。確認してから再実行してください`);
-    else if (e.code === 'EPARENT') say(`\n❌ ${path.dirname(NPMRC)} があなたの所有でないか、他のユーザーが書き込めます（安全にトークンを置けません）。権限を直してから再実行してください`);
-    else if (e.code === 'EPLATFORM') say('\n❌ この OS では安全にトークンを保存できません（macOS / Linux で実行してください）');
-    else say(`\n❌ ${NPMRC} に書けませんでした（${e.code || 'エラー'}）。ホームディレクトリの権限を確認してください`);
-    process.exit(1);
-  }
-  say('');
-  say(`✅ ${NPMRC} に登録しました（権限 600・${W.redact(token)}）`);
-
-  if (!flag('--no-verify')) {
-    say('③ 接続を確認しています…');
-    const status = await probe(token);
+  // ③ **確かめてから書く**（2026-08-26・codex R2 Q7 block の封鎖）。
+  // 旧版はここで先に `~/.npmrc` を置換し、その後で接続確認していた。誤入力・期限切れ・権限不足の
+  // トークン 1 つで、それまで動いていた別トークンとスコープ行が不可逆に消え、買い手の既存の私有
+  // パッケージ取得が購入初日に壊れていた。**probe が 200 を返すまで `~/.npmrc` は 1 バイトも触らない**。
+  const verified = !flag('--no-verify');
+  let status = null;
+  if (verified) {
+    say(`③ 接続を確認しています（${NPMRC} はまだ変更しません）…`);
+    // 第一手は npm CLI＝買い手が実際に取得に使う経路（proxy・cafile・strict-ssl が効く）
+    const n = probeNpm(token);
+    status = n.status;
+    if (status !== 200) {
+      // npm が 200 を返さなかった＝「本当に落とせない」か「npm 経路が使えない」かの区別が付かないので、
+      // **必ず**直接接続でも確かめて合成する（W.resolveProbe: どちらかが 200 なら合格）
+      if (n.note) say(`   · ${n.note}。直接接続でも確かめます（npm の proxy 設定は通りません）`);
+      status = W.resolveProbe(n.status, await probeDirect(token));
+    }
     const r = W.explainStatus(status);
     if (!r.ok) {
       say(`\n❌ ${r.message}`);
       if (r.next) say(`   → ${r.next}`);
-      // 再実行の案内: wizard が書いた `@nuwel-dev:registry=npm.pkg.github.com` のせいで素の `npx @nuwel-dev/setup` は
-      // GitHub Packages を見に行って 404 になる（codex R1 major）→ scope registry を npmjs に明示して再実行する
-      say(`   （~/.npmrc には登録済みなので、直したら次で再実行してください）`);
+      // **これが Q7 の要**: 書く前に止めたので、買い手の既存設定は無傷。そう明示しないと
+      // 「もう壊れたのでは」と疑わせるし、実際に壊していた旧版との違いが伝わらない
+      say(`   ※ ${NPMRC} は 1 バイトも変更していません（これまでの設定はそのまま残っています）`);
+      say('   （直したら次で再実行してください — scope registry の明示は 1・2 回目のどちらでも効きます）');
       say(`   npx --@nuwel-dev:registry=${W.NPMJS} @nuwel-dev/setup`);
       process.exit(1);
     }
@@ -163,19 +230,66 @@ function writeNpmrc(token) {
     say('· 接続確認は省略しました（--no-verify）');
   }
 
-  if (flag('--no-init')) { say('\n· ここまで（--no-init）。次は `npx @nuwel-dev/figma-kit init` を実行してください'); return; }
+  // 書く前に必ず通る関門。上の `explainStatus` で既に弾いているので通常は素通りする**backstop** で、
+  // 判定基準はわざと独立させてある（explainStatus は説明のための合否・こちらは status===200 ちょうど）。
+  // 片方だけを将来緩めても、もう片方が書き込みを止める。不明な形は fail-closed で拒否する。
+  const gate = W.mayWriteNpmrc({ verified, status });
+  if (!gate.ok) { say(`\n❌ 接続確認に通らなかったので中止しました（${gate.reason}）。${NPMRC} は変更していません`); process.exit(1); }
+
+  try { writeNpmrc(token); } catch (e) {
+    // エラー文にトークンが載る経路を作らない（メッセージは自前で組む）
+    say(`\n❌ ${npmrcErrorMessage(e)}`);
+    process.exit(1);
+  }
+  say('');
+  say(`✅ ${NPMRC} に登録しました（権限 600・${W.redact(token)}）`);
+  // **今書いた設定が、このウィザード自身の 2 回目を壊す**（codex R1 major の恒久案内）。
+  // `@nuwel-dev:registry=<GitHub Packages>` を ~/.npmrc に置いた以上、素の
+  // `npx @nuwel-dev/setup` は公開 npm ではなく GitHub Packages を見に行って 404 になる。
+  // 失敗してから案内するのでは遅いので、**成功した今**、次回の打ち方を渡しておく。
+  say(`   （このウィザードをもう一度実行する時は: npx --@nuwel-dev:registry=${W.NPMJS} @nuwel-dev/setup）`);
+
+  if (flag('--no-init')) { say('\n· ここまで（--no-init）。次は `npx @nuwel-dev/figma-kit@latest init` を実行してください'); return; }
 
   const dir = path.resolve(val('--dir') || process.cwd());
   say('');
   say(`④ 案件を配線します: ${dir}`);
-  const r = spawnSync('npx', ['--yes', '@nuwel-dev/figma-kit', 'init', dir], { stdio: 'inherit', env: process.env });
+  say('   （依存の取得と chromium で数分かかります。前提が合わない環境なら開始 1 秒で止まります）');
+  // **版を固定する**（codex/L3#6）: 素の `npx --yes @nuwel-dev/figma-kit` はレジストリが返した物を
+  // 無確認で install＋実行する。旧実装は `@^1` でメジャーを固定していたが、npm の semver 規則で
+  // `^1` は prerelease（1.4.0-alpha.x）に一致せず、安定版 1.x が無い間は必ず「一致する版が無い」で
+  // 落ちていた（2026-08-26 敵対レビュー block）。今は `latest` を解決 → メジャー検査 → **正確な版**で
+  // `npm exec` する（W.resolveInitVersion）。`npm exec` を使うのは、`--package=<名前>@<版>` で**取得する物**と
+  // **実行する名前**を別々に明示できるため（npx の位置引数だと版付き指定が name と混ざる）。
+  const view = spawnSync('npm', ['view', `${W.SCOPE}/figma-kit@latest`, 'version', '--json'], {
+    encoding: 'utf8', env: process.env, stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  const resolved = W.resolveInitVersion(view.status === 0 ? view.stdout : '');
+  if (!resolved.ok) {
+    say(`\n❌ figma-kit の版を解決できません: ${resolved.why}`);
+    if (view.status !== 0) say(`   npm view の失敗: ${W.explainNpmViewFailure({ status: view.status, stderr: view.stderr, spawnError: view.error && view.error.code })}`);
+    say('   トークンの権限（read:packages）と招待の Accept を確認して、同じコマンドで再実行してください');
+    process.exit(1);
+  }
+  say(`   figma-kit ${resolved.version}（latest）を使います`);
+  const r = spawnSync('npm', ['exec', '--yes', `--package=${W.SCOPE}/figma-kit@${resolved.version}`, '--', 'figma-kit', 'init', dir], {
+    stdio: 'inherit', env: process.env,
+  });
   if (r.status !== 0) {
-    say('\n❌ init が失敗しました。上の出力を確認してください（やり直しは `npx @nuwel-dev/figma-kit init`）');
+    say('\n❌ init が失敗しました。上の出力の ❌ 行を見てください（直したら同じコマンドで再開できます）');
+    say(`   やり直し: npx --yes ${W.SCOPE}/figma-kit@${resolved.version} init ${dir}`);
     process.exit(r.status === null ? 1 : r.status);
   }
   say('');
   say('=== 完了 ===');
-  say('最初に打つ 1 行: /figma-kit:intake --figma');
+  // **実在する導線だけを案内する**（L1#3）。`/implement` 等は init が案件の
+  // `.claude/commands/` へ配線したファイルで、Claude Code がそこから発見する。
+  say('① 設置の確認（必須がすべて緑になれば完了）:');
+  say(`     cd ${dir} && npx figma-kit diagnose`);
+  say('② Claude Code を開いて、最初に打つ 1 行:');
+  say('     /orchestrate            … 全体を状態機械で進める');
+  say('     /implement <セクション名>  … 1 セクションだけ実装する');
+  say('   （使えるコマンドの一覧は .claude/commands/ ・手順の説明は .claude/USAGE.md）');
 })().catch((e) => {
   // 例外の message にトークンが混ざる可能性を排除するため、種別だけを出す
   say(`\n❌ セットアップが異常終了しました（${(e && e.code) || 'エラー'}）`);

package/lib/wizard.js

@@ -56,6 +56,129 @@ function mergeNpmrc(existing, token) {
   return `${lines.join('\n')}\n`;
 }
 
+/**
+ * 接続確認を **npm CLI 経由**で行うための引数（`npm view @nuwel-dev/figma-kit version`）。
+ *
+ * なぜ生 https ではなく npm なのか（2026-08-26・codex R2 Q7）: 買い手が実際にキットを落とすのは
+ * `npm`（`npm exec … figma-kit init`）で、npm は proxy・cafile・strict-ssl・NODE_EXTRA_CA_CERTS を
+ * **自分の設定から**読む。生 `https.request` はそのどれも通らないので、企業 proxy 下では
+ * 「npm なら落とせるのに、接続確認だけが落ちる」＝**買い手を誤って止める**。
+ *
+ * **トークンは argv に載せない**（argv は同一ホストの他ユーザーから `ps` で読める）。渡し口は
+ * `npmProbeEnv` の env 1 つだけ。`--prefer-online` は「前回の 200 がキャッシュに残っていて、
+ * 期限切れトークンが通ってしまう」経路を閉じるため（再検証を強制する）。
+ *
+ * **`--@nuwel-dev:registry=` を必ず併記する**（2026-08-26 実測で判明した hollow green の封鎖）:
+ * scope 付きパッケージの取得先を決めるのは `--registry` ではなく `@scope:registry` の方で、
+ * 買い手の `~/.npmrc` に古い/誤った `@nuwel-dev:registry=` が残っていると `--registry` だけでは
+ * **そちらへ問い合わせに行く**。相手が 200 を返せば「接続できました」と出てしまい、
+ * 実際には GitHub Packages を 1 度も見ていない（＝空回りの緑）。cli の config は npmrc より強いので、
+ * 両方を argv に置いて取得先を確定させる。
+ * @returns {string[]}
+ */
+function npmProbeArgs() {
+  return [
+    'view', `${SCOPE}/figma-kit`, 'version',
+    `--${SCOPE}:registry=${REGISTRY}`,
+    `--registry=${REGISTRY}`,
+    '--prefer-online', '--loglevel=error',
+  ];
+}
+
+/**
+ * 上の `npm` に**トークンだけ**を足した env を作る（`process.env` は書き換えない）。
+ *
+ * npm は `npm_config_` 接頭の env を config として読み、**`//` で始まるキーは正規化しない**（nerf dart は
+ * そのまま）ので、`npm_config_//npm.pkg.github.com/:_authToken` が `.npmrc` の同名行と同じ意味になる。
+ * env は cli の次に強く、買い手の `~/.npmrc` に残っている**古いトークン行より優先される**（＝古い値で
+ * 401 になって新しい正しいトークンを弾く事故が起きない）。一方 proxy・cafile 等は `~/.npmrc` 側が
+ * そのまま効く（userconfig を差し替えていないため）＝この関数が proxy 対応の肝。
+ *
+ * `logs-max=0` は npm のデバッグログファイルを 1 つも作らせないため（npm は秘匿値を redact するが、
+ * **作らせない**方が確実）。
+ * @param {NodeJS.ProcessEnv} base  process.env
+ * @param {string} token
+ * @returns {NodeJS.ProcessEnv}
+ */
+function npmProbeEnv(base, token) {
+  const env = { ...(base || {}) };
+  env[`npm_config_${REGISTRY_KEY}`] = String(token);
+  env.npm_config_logs_max = '0';
+  env.npm_config_update_notifier = 'false';
+  env.npm_config_fund = 'false';
+  env.npm_config_audit = 'false';
+  return env;
+}
+
+/**
+ * `npm view` の終了状態と出力から HTTP ステータス相当を導く。
+ *
+ * **接頭辞やコードを列挙しない**（列挙は必ずその外側を穴にする）: npm は失敗を必ず `code E<数字>` の
+ * 形で出す（E401 / E403 / E404 / E500 …）ので、3 桁の数字が付いた物だけを「HTTP の判定が付いた」と見なし、
+ * それ以外（ENOTFOUND / ECONNREFUSED / ERR_TLS_* / npm 不在 / timeout）はすべて **conclusive=false**＝
+ * 「判定できなかった」に倒して生 https のフォールバックへ回す。
+ * @param {{status:number|null, output:string, spawnError:string|null}} r
+ * @returns {{status:number|null, conclusive:boolean, reason:string, note:string}}
+ */
+function classifyNpmProbe(input) {
+  // 引数欠落は「判定できなかった」＝フォールバックへ倒す（例外で落として probe ごと消さない）
+  const r = input && typeof input === 'object' ? input : {};
+  const spawnError = r.spawnError ? String(r.spawnError) : null;
+  if (spawnError === 'ENOENT') return { status: null, conclusive: false, reason: 'npm-not-found', note: 'npm が見つかりませんでした' };
+  if (spawnError === 'ETIMEDOUT') return { status: null, conclusive: false, reason: 'npm-timeout', note: 'npm が時間内に終わりませんでした' };
+  if (spawnError) return { status: null, conclusive: false, reason: `npm-spawn-${spawnError}`, note: `npm を起動できませんでした（${spawnError}）` };
+  if (r.status === 0) return { status: 200, conclusive: true, reason: 'npm-ok', note: '' };
+  const m = /(?:^|\s)code\s+E(\d{3})(?:\s|$)/m.exec(String(r.output || ''));
+  if (m) return { status: Number(m[1]), conclusive: true, reason: `npm-E${m[1]}`, note: `npm が HTTP ${m[1]} を受け取りました` };
+  if (r.status === null) return { status: null, conclusive: false, reason: 'npm-killed', note: 'npm が最後まで実行されませんでした' };
+  return { status: null, conclusive: false, reason: 'npm-unclassified', note: 'npm の応答を HTTP として判定できませんでした' };
+}
+
+/**
+ * npm 経路と直結経路の結果を合成する。
+ *
+ * **どちらか一方でも 200 なら合格**にするのが要。片方だけが通る環境が両向きに実在する:
+ *   ① 企業 proxy 下 — npm は通り、生 https は通らない
+ *   ② 未公開/prerelease だけの状態 — `npm view … version` は E404 でも packument の GET は 200
+ * どちらでも買い手は本当に取得できるので、**止めてはいけない**。合格でない時は「HTTP の判定が付いた方」を
+ * 採る（「ネットワークに出られません」より「401 でトークンが違います」の方が買い手が直せる）。
+ * @param {number|null} npmStatus
+ * @param {number|null} httpStatus
+ * @returns {number|null}
+ */
+function resolveProbe(npmStatus, httpStatus) {
+  if (npmStatus === 200 || httpStatus === 200) return 200;
+  if (typeof npmStatus === 'number') return npmStatus;
+  if (typeof httpStatus === 'number') return httpStatus;
+  return null;
+}
+
+/**
+ * **`~/.npmrc` を書いてよいか**を接続確認の結果だけから決める、唯一の口（2026-08-26・codex R2 Q7 block）。
+ *
+ * 旧版はトークンを受け取った直後に `~/.npmrc` を置換し、**その後で**接続確認していた。誤入力・期限切れ・
+ * 権限不足のトークン 1 つで、それまで動いていた別トークン（`//npm.pkg.github.com/:_authToken`）と
+ * スコープ行が不可逆に消え、買い手の既存の私有パッケージ取得が購入初日に壊れた。
+ *
+ * 判定を bin 側の `if` に散らすと同じ事故がいつでも戻せるので、**書く前に必ず通る関門**をここに置く。
+ * bin 側は `explainStatus(status).ok` が偽なら先に exit するので、通常この関門は素通りする（＝backstop）。
+ * 判定基準は独立している: `explainStatus` は買い手への説明が目的で「合否」を返し、こちらは
+ * **`status === 200` ちょうど**でしか書かせない。片方だけを緩めても、もう片方が書き込みを止める。
+ *
+ * **不明な形は書かせない**（fail-closed）: `--no-verify` は `verified === false` の明示だけを指し、
+ * 引数欠落・`verified` が真偽でない・呼び出し形の変更はすべて「判定が無い」＝拒否に倒す。
+ * 「唯一の書き込み関門」が既定で通す作りだと、将来の呼び出し追加で静かに穴になる（codex/change-review）。
+ * @param {{verified:boolean, status:number|null}} a  verified=false は `--no-verify`（明示的に確認しない指定）
+ * @returns {{ok:boolean, reason:string}}
+ */
+function mayWriteNpmrc(a) {
+  const o = a && typeof a === 'object' ? a : null;
+  if (!o || typeof o.verified !== 'boolean') return { ok: false, reason: 'no-verdict' };
+  if (o.verified === false) return { ok: true, reason: 'skip-verify' };
+  if (o.status === 200) return { ok: true, reason: 'probe-200' };
+  return { ok: false, reason: `probe-${o.status === null || o.status === undefined ? 'unreachable' : o.status}` };
+}
+
 /**
  * 接続確認の HTTP ステータスを**平語**にする。
  * 買い手が最も踏むのは 401（トークンが違う/期限切れ）と 404（招待を受けていない・
@@ -94,4 +217,136 @@ function explainStatus(status) {
   return { ok: false, message: `想定外の応答でした（HTTP ${status}）`, next: 'この行をそのまま販売元へ連絡してください' };
 }
 
-module.exports = { SCOPE, REGISTRY, NPMJS, REGISTRY_KEY, PAT_PAGE, PROBE_PATH, redact, validateTokenShape, mergeNpmrc, explainStatus };
+/**
+ * 実行中の Node がキットの床（この package.json の `engines.node`）を満たすか。
+ *
+ * なぜ入口で見るのか（2026-08-26・L6#1）: 旧版は `engines: ">=20"` を宣言していて、Node 20/21/23/25 の
+ * 買い手が**成功して進み**、PAT を発行して貼り、`.npmrc` を書き終えた**最後の 1 手**（figma-kit init）で
+ * 初めて英語の EBADENGINE を踏んでいた。発行済みのトークンが宙に浮く最悪の落ち方なので、
+ * **秘密を求める前**に日本語で止める。
+ *
+ * 判定は `^a.b.c || >=d.e.f` の形（キットの engines が実際に使う記法）だけを解釈する。
+ * **解釈できないトークンは「満たす」に倒す** — レンジは自分の package.json 由来で
+ * 外部入力ではなく、ここで買い手を誤って弾く方が害が大きい（記法の妥当性は
+ * `tools/__tests__/setup-wizard.test.js` が実レンジで固定する）。
+ * @param {string} version  process.versions.node（"22.18.0"）
+ * @param {string} range    engines.node
+ * @returns {{ok:boolean, message:string}}
+ */
+function nodeSupported(version, range) {
+  const r = String(range == null ? '' : range).trim();
+  const m = /^v?(\d+)\.(\d+)/.exec(String(version == null ? '' : version));
+  // **前提が読めない時に先へ進めない**（codex R1 major）。ここはこの直後に PAT（秘密）を尋ねる門で、
+  // レンジはこのパッケージ自身の package.json 由来＝読めないなら配布物が壊れている。
+  // 「読めないので通す」は、対応外の Node に PAT を発行させてから落とす旧挙動に戻ることを意味する。
+  if (!r || !m) {
+    return {
+      ok: false,
+      message: `対応 Node 版を判定できませんでした（宣言: ${r || '(なし)'} / 実行中: ${version}）。`
+        + '\n   配布物が壊れている可能性があります。販売元へこの行をそのまま連絡してください。',
+    };
+  }
+  const major = Number(m[1]);
+  const minor = Number(m[2]);
+  const unknown = [];
+  const satisfiesAlt = (alt) => alt.trim().split(/\s+/).filter(Boolean).every((tok) => {
+    const t = /^(>=|<=|>|<|\^|~|=)?v?(\d+)(?:\.(\d+))?/.exec(tok.replace(/([<>]=?|\^|~|=)\s+/, '$1'));
+    if (!t) { unknown.push(tok); return false; } // 未知の記法は**満たさない**側へ（読めない前提で秘密を尋ねない）
+    const op = t[1] || '=';
+    const maj = Number(t[2]);
+    const min = t[3] === undefined ? 0 : Number(t[3]);
+    switch (op) {
+      case '>=': return major > maj || (major === maj && minor >= min);
+      case '>': return major > maj || (major === maj && minor > min);
+      case '<=': return major < maj || (major === maj && minor <= min);
+      case '<': return major < maj || (major === maj && minor < min);
+      case '^': case '~': case '=': return major === maj && minor >= min;
+      default: return true;
+    }
+  });
+  if (r.split('||').some(satisfiesAlt)) return { ok: true, message: '' };
+  if (unknown.length) {
+    return {
+      ok: false,
+      message: `対応 Node 版の宣言を解釈できませんでした（読めなかった: ${unknown.slice(0, 3).join(', ')} / 宣言: ${r}）。`
+        + '\n   配布物が壊れている可能性があります。販売元へこの行をそのまま連絡してください。',
+    };
+  }
+  return {
+    ok: false,
+    message: `Node v${version} はこのキットの対応外です（対応: ${r}）。`
+      + '\n   nvm / Volta で対応版に切り替えてから、もう一度 `npx @nuwel-dev/setup` を実行してください。'
+      + '\n   （トークンはまだ作らないでください — 対応版に切り替えてからで大丈夫です）',
+  };
+}
+
+/**
+ * 秘密を安全に保存できる OS か。**トークンを尋ねる前**に判定する（L1#15）。
+ * 旧版は writeNpmrc の中で判定していたため、Windows の買い手は「所要 2 分」を読み、PAT を発行して
+ * 貼り付けた**後**で「この OS では安全にトークンを保存できません」と言われ、発行済み PAT が宙に浮いた。
+ * @returns {{ok:boolean, message:string}}
+ */
+function platformSupported({ getuid, hasNoFollow }) {
+  if (typeof getuid !== 'function' || !hasNoFollow) {
+    return {
+      ok: false,
+      message: 'この OS では安全にトークンを保存できません（macOS / Linux、または WSL2 の Linux 側で実行してください）。'
+        + '\n   （トークンはまだ作らないでください — 対応 OS で実行すれば 1 回で終わります）',
+    };
+  }
+  return { ok: true, message: '' };
+}
+
+/**
+ * init に委譲する figma-kit の版を **`latest` dist-tag から解決し、メジャーを検査して正確な版に固定する**。
+ *
+ * 2026-08-26（敵対レビュー block・prerelease-caret-resolution）: 旧実装は `--package=@nuwel-dev/figma-kit@^1`
+ * だったが、npm の semver 規則で `^1` は prerelease（1.4.0-alpha.x）に一致しない。レジストリに安定版 1.x が
+ * 1 つも無い間、買い手導線は「一致する版が無い」で必ず落ちていた。レンジで prerelease を拾うには
+ * includePrerelease が要り npm exec では指定できないため、`npm view <pkg>@latest version` で
+ * **公開側が latest に載せた版**を取り、(a) メジャーが想定と違えば fail-loud（「別メジャーの別物が
+ * 初日に降ってくる」経路は閉じたまま）(b) 通れば **その正確な版**で `npm exec` する（レンジより強い固定）。
+ *
+ * @param {string} stdout `npm view <pkg>@latest version --json` の stdout
+ * @param {{major?: number}} [opts]
+ * @returns {{ok: true, version: string} | {ok: false, why: string}}
+ */
+function resolveInitVersion(stdout, opts = {}) {
+  const major = Number.isInteger(opts.major) ? opts.major : 1;
+  let v = null;
+  try { v = JSON.parse(String(stdout || '').trim()); } catch (_) { v = null; }
+  if (Array.isArray(v)) v = v[v.length - 1]; // 複数版が返る形（レンジ指定）でも最後を採る
+  // 正準 semver のみ（数値識別子の先頭 0 は不可 — 敵対レビュー minor）
+  if (typeof v !== 'string' || !/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(-[0-9A-Za-z.-]+)?$/.test(v)) {
+    return { ok: false, why: `latest の版を取得できません（npm view の出力: ${String(stdout || '').trim().slice(0, 80) || '(空)'}）` };
+  }
+  const got = Number(v.split('.')[0]);
+  if (got !== major) return { ok: false, why: `latest の版 ${v} はメジャー ${major} ではありません（別メジャーの物は初日に入れない）` };
+  return { ok: true, version: v };
+}
+
+/**
+ * `npm view` 失敗の**理由**を買い手向けに要約する（pure・敵対レビュー block「stderr の最終行は常に
+ * 『A complete log of this run can be found in: <path>』でログパスしか出ない」への対処）。
+ * HTTP 相当は classifyNpmProbe と同じ `code E<数字>` の拾い方で位置に依存せず取り、ネットワーク系は
+ * コード名で名指しする。生の行はそのまま出さない（トークン値が混ざる余地を作らない）。
+ *
+ * @param {{status:number|null, stderr?:string, spawnError?:string|null}} r
+ * @returns {string}
+ */
+function explainNpmViewFailure(r) {
+  const c = classifyNpmProbe({ status: r && r.status, output: (r && r.stderr) || '', spawnError: (r && r.spawnError) || null });
+  if (c.status && c.status !== 200) {
+    const ex = explainStatus(c.status);
+    return `${ex.message}${ex.next ? `。${ex.next}` : ''}`;
+  }
+  const net = /\b(ECONNREFUSED|ENOTFOUND|ETIMEDOUT|ECONNRESET|EAI_AGAIN|CERT_[A-Z_]+|UNABLE_TO_[A-Z_]+)\b/.exec(String((r && r.stderr) || ''));
+  if (net) return `レジストリへ接続できませんでした（${net[1]}）。ネットワーク・プロキシ・VPN を確認して再実行してください`;
+  return `${c.note || 'npm の応答を判定できませんでした'}（exit ${r && r.status === null ? 'なし' : (r && r.status)}）`;
+}
+
+module.exports = {
+  SCOPE, REGISTRY, NPMJS, REGISTRY_KEY, PAT_PAGE, PROBE_PATH,
+  redact, validateTokenShape, mergeNpmrc, explainStatus, nodeSupported, platformSupported,
+  npmProbeArgs, npmProbeEnv, classifyNpmProbe, resolveProbe, mayWriteNpmrc, resolveInitVersion, explainNpmViewFailure,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuwel-dev/setup",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "figma-kit のセットアップウィザード（公開 npm・秘密ゼロ）。GitHub Packages のトークンを ~/.npmrc に置き、@nuwel-dev/figma-kit の init へ橋渡しする。",
   "license": "MIT",
   "private": false,
@@ -18,7 +18,7 @@
     "nuwel-setup": "bin/setup.js"
   },
   "engines": {
-    "node": ">=20"
+    "node": "^22.18.0 || ^24.11.0 || >=26.0.0"
   },
   "files": [
     "bin/",