sparkle-design-cli 1.3.8 → 1.3.10

package/README.md

@@ -1,6 +1,6 @@
 # Sparkle Design CLI
 
-デザインシステム CSS を設定ファイルから生成する CLI ツールです。
+Sparkle Design の CSS 生成、導入先プロジェクト向けのアンチパターン検査、AI エージェント向け guard 設定を行う CLI ツールです。
 
 ## インストール
 
@@ -10,7 +10,28 @@ npm install -g sparkle-design-cli
 
 ## 使用方法
 
-### 基本的な使用方法
+### サブコマンド
+
+```bash
+# CSS を生成
+npx sparkle-design-cli generate
+
+# アンチパターンを検査
+npx sparkle-design-cli check src --strict
+
+# AI 向けに JSON で検査結果と手動確認項目を取得
+npx sparkle-design-cli check src --format json
+
+# Claude / Codex / Cursor 向けの guard 設定を差し込む
+npx sparkle-design-cli setup --assistant claude
+```
+
+### 後方互換モード
+
+既存の `npx sparkle-design-cli` も引き続き動作し、内部的には `generate` として扱われます。
+ただし後方互換のための動作なので、新規利用やドキュメント上の案内では `sparkle-design-cli generate` を使用してください。
+
+### generate: 基本的な使用方法
 
 1. プロジェクトのルートディレクトリに `sparkle.config.json` ファイルを作成または配置します：
 
@@ -26,39 +47,124 @@ npm install -g sparkle-design-cli
 2. CLI ツールを実行します：
 
 ```bash
-npx sparkle-design-cli
+npx sparkle-design-cli generate
 ```
 
-または、グローバルにインストールした場合：
+既存プロジェクトでサブコマンドなしの呼び出しを使っている場合も、後方互換として次の実行方法を継続利用できます:
 
 ```bash
-sparkle-design-cli
+npx sparkle-design-cli
 ```
 
 3. `src/app/sparkle-design.css` に CSS ファイルが生成されます。
 
-### コマンドオプション
+### generate: コマンドオプション
 
 ```bash
 # ヘルプを表示
-sparkle-design-cli --help
+sparkle-design-cli generate --help
 
 # カスタム設定ファイルを指定
-sparkle-design-cli --config ./config/design.json
+sparkle-design-cli generate --config ./config/design.json
 
 # カスタム出力先を指定
-sparkle-design-cli --output ./styles/design.css
+sparkle-design-cli generate --output ./styles/design.css
 
 # 設定ファイルと出力先を両方指定
-sparkle-design-cli -c ./config/custom.json -o ./dist/styles.css
+sparkle-design-cli generate -c ./config/custom.json -o ./dist/styles.css
 ```
 
-#### オプション一覧
+#### generate オプション一覧
 
 - `-h, --help`: ヘルプメッセージを表示
 - `-c, --config <パス>`: 設定ファイルのパス（デフォルト: `./sparkle.config.json`）
 - `-o, --output <パス>`: 出力ファイルのパス（デフォルト: `./src/app/sparkle-design.css`）
 
+### check: アンチパターン検査
+
+`sparkle-design-cli check` は、導入先プロジェクトで発生しやすい Sparkle Design のアンチパターンを検出します。
+
+```bash
+# src を検査
+sparkle-design-cli check
+
+# 特定ディレクトリを strict モードで検査
+sparkle-design-cli check src/components src/features --strict
+
+# AI 向けに JSON 出力
+sparkle-design-cli check src --format json
+
+# check のヘルプを表示
+sparkle-design-cli check --help
+```
+
+#### check オプション一覧
+
+- `-h, --help`: ヘルプメッセージを表示
+- `--strict`: 違反が見つかった場合に exit code 1 で終了
+- `--format <text|json>`: 出力形式。AI 連携では `json` を推奨
+
+#### 現在検出するルール
+
+- フォーム入力に Dialog を使わない
+- DialogCancel/DialogAction を Button で二重ラップしない
+- children なしの Button に prefixIcon / suffixIcon を使わない
+- Material Symbols を className 直書きで使わない
+- shadcn/ui 既定 token を Sparkle Design 内へ持ち込まない
+
+#### Manual Review Reminders
+
+`--format json` では、機械検出できない観点も `manualReviewReminders` として返します。現在は次を含みます。
+
+- Badge と Tag の意味的な使い分け
+- CardDescription の typography / color token 明示
+- Dialog と Modal の UX 上の使い分け
+
+#### 導入先での推奨設定
+
+```json
+{
+  "scripts": {
+    "lint:sparkle": "sparkle-design-cli check src --strict"
+  }
+}
+```
+
+AI エージェントや CI からこの `lint:sparkle` を呼ぶ運用にすると、ガイドラインの注意書きだけに頼らず機械的に検査できます。
+
+### setup: AI ガード設定の差し込み
+
+`sparkle-design-cli setup` は、導入先プロジェクトの `package.json` と AI 向け指示ファイルに Sparkle Design guard を追加します。
+
+```bash
+# Claude Code 向け
+sparkle-design-cli setup --assistant claude
+
+# Codex / AGENTS.md 向け
+sparkle-design-cli setup --assistant codex
+
+# Cursor rules 向け
+sparkle-design-cli setup --assistant cursor
+
+# generic な Markdown を生成
+sparkle-design-cli setup --assistant generic
+```
+
+追加されるもの:
+- `package.json` の `lint:sparkle`
+- `package.json` の `lint:sparkle:json`
+- assistant ごとの指示ファイルへの managed block
+
+`--target` を省略した場合は `src`, `src/components`, `src/features`, `app`, `components` の順で自動検出します。既存の `lint:sparkle*` がすでに Sparkle Design 向け script なら再実行時に更新されます。独自 script は保持され、上書きしたい場合だけ `--force-script-update` を付けます。
+
+利用できる assistant:
+- `claude`: `CLAUDE.md`
+- `codex`: `AGENTS.md`
+- `cursor`: `.cursor/rules/sparkle-design-guard.mdc`
+- `generic`: `SPARKLE-DESIGN-AI.md`
+
+`setup` は通常実行時も JSON サマリーを stdout に表示します。`--dry-run` を付けると、その JSON を表示したままファイル変更だけを抑止します。
+
 ## 設定ファイル (sparkle.config.json)
 
 ### 設定ファイルの作成
@@ -105,12 +211,12 @@ sparkle-design-cli -c ./config/custom.json -o ./dist/styles.css
 生成される `globals.css`:
 
 ```css
-@import "tailwindcss";
+@import 'tailwindcss';
 /* npm パッケージのコンテンツスキャン（Tailwind がクラスを検出するために必要） */
 @source "../node_modules/@goodpatch/sparkle-design/dist";
 @source "../node_modules/@scope/my-extension-design/dist";
 /* Sparkle Design のカスタム定義（Tailwindの後にインポート） */
-@import "./sparkle-design.css";
+@import './sparkle-design.css';
 ```
 
 > **注意**: `source-packages` を指定しない場合、`@source` ディレクティブは生成されません。
@@ -192,14 +298,17 @@ npm run format:check
 ### CLI実行テスト
 
 ```bash
-# デフォルト設定でテスト
+# CSS生成
+sparkle-design-cli generate
+
+# 既存呼び出しの後方互換モード
 sparkle-design-cli
 
 # ヘルプ表示
-sparkle-design-cli --help
+sparkle-design-cli generate --help
 
-# カスタムパスでテスト
-sparkle-design-cli -c test-config.json -o test-output.css
+# 検査
+sparkle-design-cli check src --strict
 ```
 
 ## ライセンス

package/bin/sparkle-design.js

@@ -1,93 +1,252 @@
 #!/usr/bin/env node
 
 import { generateCSS } from '../lib/generate-css.js';
+import { checkProject } from '../lib/check.js';
+import { setupAssistant } from '../lib/setup.js';
 
-// コマンドライン引数を解析
-function parseArguments() {
-  const args = process.argv.slice(2);
+const SUBCOMMANDS = new Set(['generate', 'check', 'setup']);
+
+function requireOptionValue(args, index, flags) {
+  const value = args[index + 1];
+  if (!value || value.startsWith('-')) {
+    throw new Error(`Missing value for ${flags}`);
+  }
+  return value;
+}
+
+function parseGenerateOptions(args) {
   const options = {
     configPath: null,
     outputPath: null,
     help: false,
   };
 
-  for (let i = 0; i < args.length; i++) {
+  for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
 
     if (arg === '-h' || arg === '--help') {
       options.help = true;
     } else if (arg === '-c' || arg === '--config') {
-      options.configPath = args[i + 1];
-      i++; // 次の引数をスキップ
+      options.configPath = requireOptionValue(args, i, '-c/--config');
+      i += 1;
     } else if (arg === '-o' || arg === '--output') {
-      options.outputPath = args[i + 1];
-      i++; // 次の引数をスキップ
+      options.outputPath = requireOptionValue(args, i, '-o/--output');
+      i += 1;
+    } else {
+      throw new Error(`Unknown option for generate: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+function parseCheckOptions(args) {
+  const options = {
+    targets: [],
+    strict: false,
+    format: 'text',
+    help: false,
+  };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+
+    if (arg === '-h' || arg === '--help') {
+      options.help = true;
+    } else if (arg === '--strict') {
+      options.strict = true;
+    } else if (arg === '--format') {
+      const value = requireOptionValue(args, i, '--format');
+      if (value !== 'text' && value !== 'json') {
+        throw new Error(`Unsupported format for check: ${value}`);
+      }
+      options.format = value;
+      i += 1;
+    } else if (arg.startsWith('-')) {
+      throw new Error(`Unknown option for check: ${arg}`);
+    } else {
+      options.targets.push(arg);
+    }
+  }
+
+  return options;
+}
+
+function parseSetupOptions(args) {
+  const options = {
+    assistant: 'generic',
+    target: null,
+    dryRun: false,
+    forceScriptUpdate: false,
+    help: false,
+  };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+
+    if (arg === '-h' || arg === '--help') {
+      options.help = true;
+    } else if (arg === '--assistant') {
+      options.assistant = requireOptionValue(args, i, '--assistant');
+      i += 1;
+    } else if (arg === '--target') {
+      options.target = requireOptionValue(args, i, '--target');
+      i += 1;
+    } else if (arg === '--dry-run') {
+      options.dryRun = true;
+    } else if (arg === '--force-script-update') {
+      options.forceScriptUpdate = true;
+    } else {
+      throw new Error(`Unknown option for setup: ${arg}`);
     }
   }
 
   return options;
 }
 
-// ヘルプメッセージを表示
 function showHelp() {
   console.log(`
-Sparkle Design CLI - デザインシステム CSS 生成ツール
+Sparkle Design CLI
 
 使用方法:
-  sparkle-design-cli [オプション]
+  sparkle-design-cli <command> [options]
+
+Commands:
+  generate   sparkle.config.json から CSS を生成
+  check      Sparkle Design のアンチパターンを検査
+  setup      AI エージェント向けの guard 設定を導入
 
-基本的な使用方法:
-  1. プロジェクトのルートディレクトリに sparkle.config.json ファイルを作成または配置
-  2. CLI ツールを実行: sparkle-design-cli
-  3. src/app/sparkle-design.css に CSS ファイルが生成されます
+後方互換:
+  sparkle-design-cli [generate options]
+  サブコマンドなしの実行は現在も generate として動作しますが、
+  正式リリース時に削除予定です。今後は sparkle-design-cli generate を使ってください。
 
-オプション:
+Generate:
+  sparkle-design-cli generate
+  sparkle-design-cli generate --config ./config/design.json
+  sparkle-design-cli generate --output ./styles/design.css
+  sparkle-design-cli generate -c ./config/custom.json -o ./dist/styles.css
+
+Check:
+  sparkle-design-cli check
+  sparkle-design-cli check src --strict
+  sparkle-design-cli check src --format json
+  sparkle-design-cli check src/components src/features
+
+Setup:
+  sparkle-design-cli setup --assistant claude
+  sparkle-design-cli setup --assistant codex --target src
+  sparkle-design-cli setup --assistant cursor --dry-run
+  sparkle-design-cli setup --assistant claude --force-script-update
+
+Generate options:
   -h, --help                 このヘルプメッセージを表示
-  -c, --config <パス>        設定ファイルのパス (デフォルト: ./sparkle.config.json)
-  -o, --output <パス>        出力ファイルのパス (デフォルト: ./src/app/sparkle-design.css)
-
-使用例:
-  sparkle-design-cli
-  sparkle-design-cli --config ./config/design.json
-  sparkle-design-cli --output ./styles/design.css
-  sparkle-design-cli -c ./config/custom.json -o ./dist/styles.css
-
-設定ファイル (sparkle.config.json):
-  設定ファイルは専用のプラグインから自動生成することを推奨します。
-  プロジェクトのルートディレクトリに配置してください。
-
-  設定例:
-  {
-    "primary": "blue",
-    "font-pro": "BIZ UDPGothic",
-    "font-mono": "BIZ UDGothic",
-    "radius": "md"
-  }
+  -c, --config <path>        設定ファイルのパス (default: ./sparkle.config.json)
+  -o, --output <path>        出力ファイルのパス (default: ./src/app/sparkle-design.css)
 
-  設定オプション:
-  - primary: プライマリカラー (blue, red, orange など)
-  - font-pro: プロポーショナルフォント (Google Fonts の名前)
-  - font-mono: モノスペースフォント (Google Fonts の名前)
-  - radius: 角丸設定 (sm, md, lg など)
+Check options:
+  -h, --help                 このヘルプメッセージを表示
+  --strict                   違反があれば exit code 1 で終了
+  --format <text|json>       出力形式 (default: text)
 
-出力:
-  - デフォルト出力先: src/app/sparkle-design.css
-  - カスタム出力先: -o オプションで指定可能
-  - 実行場所を基準として相対パスで処理されます
+Setup options:
+  -h, --help                 このヘルプメッセージを表示
+  --assistant <name>         claude / codex / cursor / generic (default: generic)
+  --target <path>            lint 対象パス (default: auto-detect)
+  --dry-run                  ファイルを変更せず結果だけ表示
+  --force-script-update      既存の lint:sparkle 系 script も上書きする
+
+Check で検出する主なパターン:
+  - フォーム入力に Dialog を使っている
+  - DialogCancel / DialogAction を <Button> で二重ラップしている
+  - children なしの Button に prefixIcon / suffixIcon を使っている
+  - Material Symbols を className 直書きしている
+  - text-muted-foreground / bg-background / border-border を持ち込んでいる
+
+JSON 出力では manualReviewReminders も返すため、AI から実行する場合は --format json を推奨
 `);
 }
 
-// メイン処理
-function main() {
-  const options = parseArguments();
+function showGenerateDeprecationNotice() {
+  console.warn(
+    '[sparkle-design-cli] Running without a subcommand defaults to `generate`. ' +
+      'Use `sparkle-design-cli generate` instead. This compatibility mode will be removed at the formal release.'
+  );
+}
 
-  if (options.help) {
-    showHelp();
-    process.exit(0);
-  }
+function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
 
   try {
-    generateCSS(options.configPath, options.outputPath);
+    if (args.length === 0) {
+      showGenerateDeprecationNotice();
+      generateCSS();
+      return;
+    }
+
+    if (command === '-h' || command === '--help') {
+      showHelp();
+      process.exit(0);
+    }
+    if (command === 'generate') {
+      const options = parseGenerateOptions(args.slice(1));
+
+      if (options.help) {
+        showHelp();
+        process.exit(0);
+      }
+
+      generateCSS(options.configPath, options.outputPath);
+      return;
+    }
+
+    if (command === 'check') {
+      const options = parseCheckOptions(args.slice(1));
+
+      if (options.help) {
+        showHelp();
+        process.exit(0);
+      }
+
+      const hasFindings = checkProject(options.targets, {
+        strict: options.strict,
+        format: options.format,
+      });
+      if (hasFindings && options.strict) {
+        process.exit(1);
+      }
+      return;
+    }
+
+    if (command === 'setup') {
+      const options = parseSetupOptions(args.slice(1));
+
+      if (options.help) {
+        showHelp();
+        process.exit(0);
+      }
+
+      setupAssistant(options);
+      return;
+    }
+
+    if (!SUBCOMMANDS.has(command) && command.startsWith('-')) {
+      showGenerateDeprecationNotice();
+      const options = parseGenerateOptions(args);
+
+      if (options.help) {
+        showHelp();
+        process.exit(0);
+      }
+
+      generateCSS(options.configPath, options.outputPath);
+      return;
+    }
+
+    if (!SUBCOMMANDS.has(command)) {
+      throw new Error(`Unknown command: ${command}`);
+    }
   } catch (error) {
     console.error('❌ エラーが発生しました:', error.message);
     process.exit(1);