google-zx-scripting

Google ZX スクリプティング

Google の zx ライブラリを使ってスクリプトを作成する際に、このスキルを使用します。zx は、JavaScript／TypeScript でのシェルスクリプティングを生産的かつ安全にするツールです。タスクに必要なリファレンスファイルだけを読みます。

クイックスタート

移植性を高めるため、すべての zx スクリプトで lite エントリーポイントを使用します。スクリプトは単独で実行できる .mjs ファイルで、プロジェクトのセットアップは不要です。

#!/usr/bin/env npx zx

import { $, fs, path, glob, chalk } from 'zx/core';

const files = await glob('src/**/*.ts');
await $`eslint ${files}`;

直接実行します。

chmod +x script.mjs && ./script.mjs
# or
npx zx script.mjs

重要なルール

1. 必ず zx/core を使用してください。zx のみのインポートは避けてください。重い CLI ラッパーを回避できます。
2. テンプレートリテラルは自動的にエスケープされます。$`echo ${userInput}` は安全です。展開される変数を手動で引用符で囲まないでください。
3. 配列は正しく展開されます。$`cmd ${arrayOfArgs}` は各要素を個別の引用符付き引数として展開します。
4. ゼロ以外の終了コードは例外を発生させます。失敗が予想される場合（例：一致するものがない grep）は、.nothrow() を使用して抑制します。
5. 分離には within() を使用します。独自の $.cwd と $.env を持つ非同期スコープを作成します。並列タスクでは不可欠です。
6. .pipe() でパイプします。シェルの | の代わりに $`cmd1`.pipe($`cmd2`) を使用します。
7. zx の組み込み機能を優先します。find の代わりに glob()、cat／cp／mv の代わりに fs、curl の代わりに fetch() を使用します。
8. cd() はグローバルです。スコープを限定したディレクトリ変更には within() または $({cwd: '/path'}) を使用します。
9. スクリプトは .mjs にする必要があります。バンドラーの設定なしでトップレベルの await をサポートできます。

リファレンス一覧

必要な項目	ファイル
$、ProcessPromise、ProcessOutput、設定、パイプ処理、ストリーム	references/core-api.md
単発スクリプト、CLI ツール、ビルドスクリプト、デプロイ、プロジェクトのひな形作成	references/scripting-patterns.md
ファイル処理、データパイプライン、バッチ処理、AI スクリプト、ログ分析	references/processing-recipes.md

タスクの振り分け

• 手早く実行する単発コマンドやシェル自動化を作成する → references/scripting-patterns.md
• ビルド／デプロイ／CI スクリプトを作成する → references/scripting-patterns.md
• ファイル、データ、ログ、またはバッチ処理を扱う → references/processing-recipes.md
• $、パイプ、ストリーム、設定の API 詳細が必要 → references/core-api.md
• 複数のパターンを組み合わせる（例：ビルド＋処理）→ 関連する両方のファイルを読む

インポート早見表

// Core — always start here
import { $, fs, path, glob, chalk } from 'zx/core';

// Additional utilities (import individually as needed)
import { spinner, retry, question, echo, sleep, within,
         stdin, tmpdir, tmpfile, which, ps, kill,
         quote, YAML, argv, fetch } from 'zx/core';

検証チェックポイント

破壊的な操作や大量処理を実行する前に、必ず対象範囲を確認してください。

// Verify glob matches before bulk processing
const files = await glob('src/**/*.ts');
console.log(`Found ${files.length} files`);
if (files.length === 0) throw new Error('No files matched — check glob pattern');
if (files.length > 500) throw new Error(`Too many files (${files.length}) — narrow the glob`);

// Dry-run flag for destructive operations
const dryRun = argv['dry-run'] ?? false;
for (const file of files) {
    if (dryRun) { console.log(`[dry-run] would delete ${file}`); continue; }
    await fs.rm(file);
}

並列処理では、部分的な失敗に対応するため Promise.allSettled() を使用します。

const results = await Promise.allSettled(
    files.map(f => within(async () => $`process ${f}`))
);
const failed = results.filter(r => r.status === 'rejected');
if (failed.length > 0) {
    console.error(chalk.red(`${failed.length}/${results.length} tasks failed`));
    failed.forEach(r => console.error(r.reason));
    process.exitCode = 1;
}

生成スクリプトの規約

1. Shebang 行：必ず #!/usr/bin/env npx zx を1行目に記述します
2. 詳細表示をオフ：コマンドのエコーを抑制するため、メインロジックの前に $.verbose = false を設定します
3. エラー処理：main().catch() パターンを使用します。ロジックを async function main() でラップし、続けて main().catch(err => { console.error(chalk.red(err.message)); process.exit(1); }) を呼び出します
4. 出力の色：成功には chalk.green()、エラーには chalk.red()、警告には chalk.yellow()、補足情報には chalk.dim() を使用します
5. 進捗状況：対話型のコンテキストで時間のかかる操作を行う場合は、spinner() を使用します
6. 引数：CLI 引数の処理には argv（事前解析済みの minimist）を使用します
7. 一時ファイル：tmpdir() と tmpfile() を使用します。終了時に自動でクリーンアップされます
8. 並列処理：分離が必要な並列操作には、within() と組み合わせて Promise.all() を使用します