windowsfy

windowsfy

Node.js プロジェクトの package.json スクリプトをスキャンし、Windows のネイティブシェル（CMD および PowerShell 5.1）で失敗する Unix 専用のパターンを検出して、ユーザーの確認後に移植性のある修正を適用します。各検出項目は、推奨されるクロスプラットフォーム形式（cross-env、shx、glob を使用）またはシェル固有の代替形式（CMD、PowerShell、Bash 系のネイティブ構文）で修正できます。

カテゴリ

カテゴリ	説明	参照
native-dep	MS BuildTools が必要な C++ アドオンパッケージ（tfjs-node、better-sqlite3）。	native-deps
inline-env	CMD と PowerShell ではサポートされない KEY=val node … 形式のプレフィックス。	inline-env-vars
single-quote	CMD ではシングルクォートが文字どおり渡されるため、--message 'text' は失敗します。	single-quotes
unix-cmd	rm -rf、chmod、cp -r、mv、mkdir -p は Windows シェルにありません。	unix-commands
glob-expand	CMD/PS は **/*.test.ts を展開せず、リテラル文字列がバイナリに渡されます。	glob-patterns
ps5-ampamp	PowerShell 5.1 は対話型の && を拒否します（npm スクリプトでは動作します）。	powershell-5-operator

プラットフォーム要件（必須）

このスキルはWindows のネイティブシェルでのみ実行されます。

• サポート対象：cmd.exe、powershell.exe（PS 5.1）、pwsh.exe（PS 7 以降）。
• 対象外：Linux、macOS、WSL、Git Bash / MSYS2 / Cygwin、mintty。

対象外の環境ではすでに POSIX シェルのセマンティクスが利用でき、troubleshooting/windows/commons.md のスクリプトはそこで正しく実行されます。そのため、windowsfy を実行すると不要な devDependencies が追加されたり、必要のない箇所にシェル固定の代替形式が適用されたりする可能性があります。上書きフラグはありません。

実行方法

/windowsfy [path]

• [path] にはディレクトリ、単一の package.json、または省略を指定できます。
• 省略した場合 → ./（現在の作業ディレクトリを再帰的にスキャン）。
• ディレクトリの場合 → そのディレクトリから再帰的にスキャン。
• package.json ファイルの場合 → そのファイルのみをスキャン。
• 上記以外（存在しないパス、package.json ではないファイル）の場合 → 明確なエラーを表示して中止。

ステップ 0 — 環境ガード（毎回、最初に実行）

パスを解析する前に、次を実行します。

node <skill-dir>/scripts/scan.mjs --check-env --json

JSON オブジェクト {"env":"...","allowed":true|false,"reason":"..."} を解析します。

• allowed === false の場合：検出された env と reason を表示して停止します。パスを解析しないでください。スキャナーを呼び出さないでください。ファイルを編集しないでください。
• allowed === true の場合：ステップ 1 に進みます。

スキャナーは他のすべてのモードでも内部的に detectEnv() を実行するため、このステップを省略しても、--root/--file は stderr メッセージを出して終了コード 2 で終了します。

ステップ 0b — ユーザーが使用している対話型シェルを確認する

環境ガードを通過したら、AskUserQuestion を使ってユーザーが使用しているシェルを確認します。自動検出は行わず、次の 3 つから選択してもらいます。

1. CMD (cmd.exe)
2. Windows PowerShell 5.x (powershell.exe) — Windows 10 および 11 のデフォルト
3. PowerShell 7+ (pwsh.exe)

回答を $SHELL_CHOICE に cmd、ps5、ps7 のいずれかの値で保存します。以降のすべての scan.mjs の呼び出しで、--shell $SHELL_CHOICE を渡します。

この選択は、次の 2 つに影響します。

1. スキャナーの重大度マトリックス — ps5-ampamp は ps5 の場合のみ info として報告されます。cmd と ps7 では、&& がどちらでもネイティブに動作するため、報告されません。その他のすべてのカテゴリは、選択にかかわらず error のままです。Windows では npm がデフォルトで cmd.exe を通じてスクリプトを起動するため、ユーザーの対話型シェルが PowerShell でも、スクリプトの実行環境は CMD だからです。
2. ステップ 6 のフォールバック順序 — $SHELL_CHOICE に対応するフォールバックは、クロスプラットフォームの選択肢の直後、つまり 2 番目に表示し、自然な代替手段として強調します。

シェルごとの重大度マトリックス

カテゴリ	cmd	ps5	ps7
native-dep	info	info	info
inline-env	error	error	error
single-quote	error	error	error
unix-cmd	error	error	error
glob-expand	error	error	error
ps5-ampamp	報告なし	info	報告なし

ステップ 1 — 引数の処理

1. ユーザーの呼び出しから [path] を抽出します。空の場合は ./ として扱います。

2. 絶対パスに解決します。realpath を使う Bash、または node -e "console.log(require('path').resolve(...))" を使います。

3. パスを分類します。

   if [ -d "$P" ]; then echo dir
   elif [ -f "$P" ]; then echo file
   else echo missing
   fi
   

4. 適用します（必ず --shell $SHELL_CHOICE を含めてください）。

   • dir → node <skill-dir>/scripts/scan.mjs --root <abs-path> --shell $SHELL_CHOICE --json。
   • file → ファイル名は package.json でなければなりません。node <skill-dir>/scripts/scan.mjs --file <abs-path> --shell $SHELL_CHOICE --json。
   • missing → windowsfy: path not found: <input> を表示して停止します。

ステップ 2 — 検出されるパターン

#	カテゴリ	Windows で発生する問題	重大度
1	native-dep	C++ アドオンを含むパッケージのインストールには MS BuildTools が必要です（@tensorflow/tfjs-node、better-sqlite3、@huggingface/transformers、@xenova/transformers）。	info
2	inline-env	KEY=val node … — Windows では KEY=val がコマンド名として扱われます。	error
3	single-quote	--message 'text' — CMD ではシングルクォートがそのまま渡されます。	error
4	unix-cmd	rm -rf、chmod、cp -r、mv、mkdir -p — Windows にはありません。	error
5	glob-expand	tests/**/*.test.ts — CMD と PS は glob を展開せず、文字列がそのままプログラムに渡されます。	error
6	ps5-ampamp	PS 5.1 では && を使うと ParserError: The token '&&' is not a valid statement separator が発生します。	info

ステップ 3 — 検出ワークフロー

1. スキャナーの --json 出力から、検出結果を category ごとにまとめます。
2. 概要テーブルを作成します：Category | Files affected | Severity。
3. 概要をユーザーに表示します。
4. 検出結果が 0 件のカテゴリについては、以降のステップをスキップします。

Step 4 — 修正するカテゴリの確認

AskUserQuestion を使って、ユーザーが修正を希望するカテゴリを尋ねます。事前に次の説明を提示します。

• native-dep（情報）→ references/native-deps.md に記載されている手動の winget インストール手順。package.json の編集はありません。
• ps5-ampamp（情報）→ PowerShell 7 をインストールします。デフォルトでは package.json の編集はありません（PowerShell 固定のフォールバックがあります）。
• それ以外のすべてのカテゴリ → 自動修正可能です。

Step 5 — 修正スタイルの選択

Step 4 でユーザーが確認したカテゴリに対して、適用するスタイルを全体でどれにするか（AskUserQuestion を1回）尋ねます。ユーザーのシェルに対応するフォールバックが2番目に表示されるよう、$SHELL_CHOICE に基づいてオプションの順序を並べます。

$SHELL_CHOICE	オプションの順序
cmd	1. クロスプラットフォーム · 2. CMD フォールバック · 3. PowerShell フォールバック · 4. 検出結果ごと
ps5 または ps7	1. クロスプラットフォーム · 2. PowerShell フォールバック · 3. CMD フォールバック · 4. 検出結果ごと

オプションの説明：

1. クロスプラットフォーム（推奨） — cross-env、shx、glob。どこでも動作します。devDependencies が追加されます。
2. CMD フォールバック — cmd /V:ON /C "set KEY=val & node …"、rmdir /S /Q。スクリプトを CMD 専用にします。
3. PowerShell フォールバック — $env:KEY='val'; node …、Remove-Item -Recurse -Force。スクリプトを PS 専用にします。
4. 検出結果ごと — 検出結果ごとに個別に尋ねます。

Windows ネイティブ環境では Bash 系のフォールバックを意図的に省略します（ここでは意味がありません。ユーザーは CMD または PowerShell を実行しています）。カテゴリにフォールバックがない場合（例：glob-expand、CMD での chmod）、そのカテゴリでは黙ってクロスプラットフォームに切り替え、出力でその旨を伝えます。

Step 6 — 修正スタイルのオプション一覧

#	カテゴリ	クロスプラットフォーム（優先）	CMD フォールバック	PowerShell フォールバック	Bash 系フォールバック
2	inline-env	cross-env KEY=val node …	cmd /V:ON /C "set KEY=val & node …"	$env:KEY='val'; node …	KEY=val node … を維持
3	single-quote	\"…\" にエスケープ	\"…\" にエスケープ（CMD では必須）	'…' を維持するか、エスケープ	'…' を維持
4a	unix-cmd（rm -rf）	shx rm -rf folder	rmdir /S /Q folder	Remove-Item -Recurse -Force folder	rm -rf folder を維持
4b	unix-cmd（chmod）	shx chmod 755 file（Win では何もしない）	ネイティブな同等コマンドなし — 切り替え	ネイティブな同等コマンドなし — 切り替え	chmod 755 file を維持
5	glob-expand	dir（Node 22+）または glob -c "…" "…**"	フォールバックなし — 切り替え	フォールバックなし — 切り替え	フォールバックなし — 切り替え
6	ps5-ampamp	PS 7 をインストール（手動）	該当なし — && は CMD で動作します	PS 5.1：cmd1; if ($?) { cmd2 }	該当なし — && は動作します

各カテゴリの完全な差分とエッジケースは references/<topic>.md に記載されています。

Step 7 — 修正の適用

影響を受ける package.json ごとに、すでに変更した文字列の再整形を避けるため、次の順序でカテゴリを修正します。

1. unix-cmd
2. inline-env
3. single-quote
4. glob-expand

ルール：

• Edit を使い、スクリプト値ごとに対象を絞った編集を1回行います。ファイル全体を書き換えてはいけません。
• クロスプラットフォームのスタイルが選択され、編集によって新しいツールが追加された場合は、そのツールが dependencies／devDependencies にまだ存在しない場合に限り、その package.json のディレクトリで npm install --save-dev <pkg> を実行します。
  • inline-env のクロスプラットフォーム → cross-env
  • unix-cmd のクロスプラットフォーム → shx
  • glob-expand のオプション B → glob
• シェル固有のフォールバックでは、devDependency を追加しません。

ステップ 8 — 検証

同じパス／モード（--root または --file）でスキャナーを再実行します。修正したカテゴリは表示されなくなります。残った検出結果は誤検出の可能性が高いため（例：unix-cmd による sed の検出）、手動レビュー用に提示します。

検出スクリプトを直接使用する

node scan.mjs --check-env [--json]
node scan.mjs [--root <dir> | --file <path/to/package.json>] [--shell <cmd|ps5|ps7>] [--json]

--shell のデフォルトは cmd（最も厳格）です。無効な値を指定すると、コード 64 で終了します。

終了コード：

• 0 成功／環境が許可されている
• 2 環境が Windows ネイティブではない、またはパスが見つからない
• 64 CLI 引数が無効

人間が読める形式の出力：

<rel-path>/package.json:<script-name>: [category] <snippet>
<rel-path>/package.json: [native-dep] @tensorflow/tfjs-node

JSON 出力：{file, script, category, severity, snippet, fix} の配列（--check-env の場合は env オブジェクト）

差分の例

• examples/cross-env-before-after.json
• examples/shx-rm-rf-before-after.json
• examples/shx-chmod-before-after.json
• examples/single-quotes-before-after.json
• examples/glob-directory-before-after.json
• examples/native-deps-flag.json

警告とエッジケース

• Windows では shx chmod は何もせずに終了します。 Windows のファイルシステムには実行ビットがありません。Linux CI／デプロイで実行ビットが必要な場合は、process.platform で条件分岐する fs.chmodSync を使った Node スクリプトに置き換えてください。
• Windows では @tensorflow/tfjs-node に Node 24 が必要です。 troubleshooting/windows/commons.md によると、Node 22 はサポートされていません。移行については https://nodejs.org/en/blog/migrations/v22-to-v24 を参照してください。
• PS 5.1 の && は package.json 内で自動修正できません。 スキャナーはこれを error ではなく info として報告します。&& を ; に書き換えないでください。Unix での実行に支障が出ます。PS に固定した書き換え（cmd1; if ($?) { cmd2 }）は、あくまで代替手段です。
• 誤検出。 sed、シングルクォートを含む URL、意図的に Unix 専用としているスクリプトなどです。--json の snippet フィールドを使うと、修正の適用前にユーザーが検出結果の選択を解除できます。
• cross-env の二重ラップ防止。 cross-env が KEY=value トークンより前に現れる値は、スキャナーがスキップします。&& cross-env KEY=val node … のような連結形式は、処理済みとして認識されます。
• シェル固定の代替手段を使うと、移植性が変わります。 ユーザーが CMD または PS の代替手段を選択すると、package.json はそのシェルに固定され、他のシェルではスクリプトが動作しなくなります。選択したシェルをプロジェクトの README に記載することを推奨します。
• スタイルが混在するプロジェクト。 ユーザーが明示的に「per-finding」を選択していない限り、同じ package.json 内で主要なスタイルと代替スタイルを混在させないでください。
• 環境ガードを上書きする方法はありません。 このスキルは Linux、macOS、WSL、Git Bash、MSYS2、Cygwin で実行させることはできません。これらの環境から必要な場合は、references/*.md を使って手動で差分を適用してください。
• Windows での npm の script-shell は、デフォルトで cmd.exe です。 ユーザーがステップ 0b で ps5 または ps7 を選んだ場合でも、single-quote と unix-cmd は引き続き error になります。これらのエラーは対話型シェルではなく、npm run が起動する cmd.exe 内でのスクリプト実行時に発生するためです。シェルの選択によって影響を受けるカテゴリは ps5-ampamp のみです。このカテゴリは、&& がネイティブに動作する cmd と ps7 では検出されなくなります。ユーザーが npm config set script-shell powershell.exe を実行している場合（一般的ではありません）、実行時の動作は異なります。このスキルはその設定を検出しません。