sparkle-design-cli 1.6.2 → 2.0.0

package/README.md

@@ -1,6 +1,27 @@
 # Sparkle Design CLI
 
-Sparkle Design の CSS 生成、導入先プロジェクト向けのアンチパターン検査、AI エージェント向け guard 設定を行う CLI ツールです。
+Sparkle Design のプロジェクト初期セットアップ、CSS 生成、導入先プロジェクト向けのアンチパターン検査、AI エージェント向け guard 設定を行う CLI ツールです。
+
+## クイックスタート
+
+既存の Next.js / Vite プロジェクトに Sparkle Design を導入する場合、以下 1 コマンドで完了します：
+
+```bash
+npx --yes sparkle-design-cli setup --assistant claude
+```
+
+setup は次を自動で行います:
+
+1. パッケージマネージャー（pnpm / npm / yarn / bun）を自動検出
+2. `sparkle-design` を dependencies、`tailwindcss` + `@tailwindcss/postcss` を devDependencies に追加
+3. 未作成の場合のみ初期ファイルを生成:
+   - `sparkle.config.json`（デフォルトは blue / Inter / JetBrains Mono / md）
+   - `postcss.config.mjs`
+   - `src/app/globals.css`（または `src/globals.css`）
+4. AI 指示ファイル（`CLAUDE.md` / `AGENTS.md` / Cursor rules）に Sparkle Design Guard ブロックを追加
+5. `sparkle-design-cli generate` を実行し、`sparkle-design.css` と `SparkleHead.tsx` を生成
+
+既存ファイルは上書きされません。
 
 ## インストール
 
@@ -8,11 +29,16 @@ Sparkle Design の CSS 生成、導入先プロジェクト向けのアンチパ
 npm install -g sparkle-design-cli
 ```
 
+> `npx --yes sparkle-design-cli ...` で都度実行する運用を推奨します（常に最新版が利用されます）。
+
 ## 使用方法
 
 ### サブコマンド
 
 ```bash
+# プロジェクト全体を一気にセットアップ（推奨・新規導入時）
+npx --yes sparkle-design-cli setup --assistant claude
+
 # CSS を生成
 npx sparkle-design-cli generate
 
@@ -21,9 +47,6 @@ npx sparkle-design-cli check src --strict
 
 # AI 向けに JSON で検査結果と手動確認項目を取得
 npx sparkle-design-cli check src --format json
-
-# Claude / Codex / Cursor 向けの guard 設定を差し込む
-npx --yes sparkle-design-cli setup --assistant claude
 ```
 
 ### 後方互換モード
@@ -141,12 +164,18 @@ sparkle-design-cli check --help
 
 AI エージェントや CI からこの `lint:sparkle` を呼ぶ運用にすると、ガイドラインの注意書きだけに頼らず機械的に検査できます。
 
-### setup: AI ガード設定の差し込み
+### setup: プロジェクトのフルセットアップ
+
+`sparkle-design-cli setup` は、Sparkle Design の導入に必要な作業をまとめて行います：
 
-`sparkle-design-cli setup` は、導入先プロジェクトの `package.json` と AI 向け指示ファイルに Sparkle Design guard を追加します。
+1. **パッケージマネージャーの検出**（pnpm / yarn / bun / npm）
+2. **パッケージのインストール** — `sparkle-design`（dependencies）、`tailwindcss` + `@tailwindcss/postcss`（devDependencies）
+3. **初期ファイルの生成** — `sparkle.config.json` / `postcss.config.mjs` / `globals.css` が無い場合のみ作成
+4. **AI ガード設定** — `CLAUDE.md` などに Sparkle Design Guard ブロックと `lint:sparkle` script を追加
+5. **`generate` の実行** — `sparkle-design.css` と `SparkleHead.tsx` を生成
 
 ```bash
-# Claude Code 向け
+# Claude Code 向けフルセットアップ
 npx --yes sparkle-design-cli setup --assistant claude
 
 # Codex / AGENTS.md 向け
@@ -155,16 +184,16 @@ npx --yes sparkle-design-cli setup --assistant codex
 # Cursor rules 向け
 npx --yes sparkle-design-cli setup --assistant cursor
 
-# generic な Markdown を生成
-npx --yes sparkle-design-cli setup --assistant generic
+# AI ガードだけ追加したい場合（パッケージインストール・scaffold・generate をスキップ）
+npx --yes sparkle-design-cli setup --assistant claude --skip-install --skip-scaffold --skip-generate
 ```
 
-追加されるもの:
-- `package.json` の `lint:sparkle`
-- `package.json` の `lint:sparkle:json`
-- assistant ごとの指示ファイルへの managed block
+既存ファイルは上書きされません:
+- `sparkle.config.json` / `postcss.config.*` / `globals.css` が存在する場合はそのまま保持
+- 既に依存関係に入っているパッケージはインストールをスキップ
+- `package.json` の既存の `lint:sparkle*` 独自 script は保持（`--force-script-update` で上書き）
 
-`--target` を省略した場合は `src`, `src/components`, `src/features`, `app`, `components` の順で自動検出します。既存の `lint:sparkle*` がすでに Sparkle Design 向け script なら再実行時に更新されます。独自 script は保持され、上書きしたい場合だけ `--force-script-update` を付けます。
+`--target` を省略した場合、lint 対象は `src`, `src/components`, `src/features`, `app`, `components` の順で自動検出されます。
 
 利用できる assistant:
 - `claude`: `CLAUDE.md`
@@ -172,6 +201,17 @@ npx --yes sparkle-design-cli setup --assistant generic
 - `cursor`: `.cursor/rules/sparkle-design-guard.mdc`
 - `generic`: `SPARKLE-DESIGN-AI.md`
 
+#### setup オプション一覧
+
+- `--assistant <name>`: claude / codex / cursor / generic (default: generic)
+- `--target <path>`: lint 対象パス (default: auto-detect)
+- `--instructions-path <path>`: AI 指示ファイルの出力先パス (default: アシスタント別のデフォルト)
+- `--skip-install`: パッケージインストールをスキップ
+- `--skip-scaffold`: 初期ファイル生成をスキップ
+- `--skip-generate`: `generate` 実行をスキップ
+- `--dry-run`: ファイルを変更せず結果だけ表示
+- `--force-script-update`: 既存の `lint:sparkle` 系 script も上書き
+
 `setup` は通常実行時も JSON サマリーを stdout に表示します。`--dry-run` を付けると、その JSON を表示したままファイル変更だけを抑止します。
 
 ## 設定ファイル (sparkle.config.json)
@@ -238,7 +278,7 @@ Figma プラグインが出力する基本4項目に加えて、プロジェク
 
 #### extend.source-packages
 
-`@goodpatch/sparkle-design` を npm パッケージとして利用する場合に必須。`globals.css` に `@source` ディレクティブを自動挿入します。`@goodpatch/sparkle-design` は常にデフォルトで含まれます。
+`sparkle-design` を npm パッケージとして利用する場合に必須。`globals.css` に `@source` ディレクティブを自動挿入します。`sparkle-design` は常にデフォルトで含まれます。
 
 #### extend.custom-css
 

package/bin/sparkle-design.js

@@ -83,6 +83,9 @@ function parseSetupOptions(args) {
     instructionsPath: null,
     dryRun: false,
     forceScriptUpdate: false,
+    skipInstall: false,
+    skipScaffold: false,
+    skipGenerate: false,
     help: false,
   };
 
@@ -104,6 +107,12 @@ function parseSetupOptions(args) {
       options.dryRun = true;
     } else if (arg === '--force-script-update') {
       options.forceScriptUpdate = true;
+    } else if (arg === '--skip-install') {
+      options.skipInstall = true;
+    } else if (arg === '--skip-scaffold') {
+      options.skipScaffold = true;
+    } else if (arg === '--skip-generate') {
+      options.skipGenerate = true;
     } else {
       throw new Error(`Unknown option for setup: ${arg}`);
     }
@@ -122,7 +131,7 @@ Sparkle Design CLI
 Commands:
   generate   sparkle.config.json から CSS を生成
   check      Sparkle Design のアンチパターンを検査
-  setup      AI エージェント向けの guard 設定を導入
+  setup      Sparkle Design プロジェクトをセットアップ（パッケージ導入 + 初期ファイル + AI ガード + generate）
 
 後方互換:
   sparkle-design-cli [generate options]
@@ -142,7 +151,11 @@ Check:
   sparkle-design-cli check src/components src/features
 
 Setup:
-  sparkle-design-cli setup --assistant claude
+  sparkle-design-cli setup                                        # フルセットアップ（推奨・新規導入時）
+  sparkle-design-cli setup --assistant claude                     # Claude 向けガードも同時にセットアップ
+  sparkle-design-cli setup --skip-install                         # パッケージインストールをスキップ
+  sparkle-design-cli setup --skip-scaffold                        # 初期ファイル生成をスキップ
+  sparkle-design-cli setup --skip-generate                        # generate 実行をスキップ
   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
@@ -193,6 +206,16 @@ Setup options:
   --dry-run                  ファイルを変更せず結果だけ表示
   --instructions-path <path> AI 指示ファイルの出力先パス (default: アシスタント別のデフォルト)
   --force-script-update      既存の lint:sparkle 系 script も上書きする
+  --skip-install             パッケージインストール（sparkle-design, tailwindcss）をスキップ
+  --skip-scaffold            初期ファイル（sparkle.config.json, postcss.config, globals.css）生成をスキップ
+  --skip-generate            generate 実行をスキップ
+
+Setup の動作:
+  1. パッケージマネージャー検出（pnpm / npm / yarn / bun）
+  2. sparkle-design を dependencies に追加、tailwindcss + @tailwindcss/postcss を devDependencies に追加
+  3. sparkle.config.json / postcss.config.mjs / globals.css が無ければ初期ファイルを生成
+  4. AI アシスタントのガードブロックを指定ファイルに挿入（存在しなければ新規作成）
+  5. sparkle-design-cli generate を実行し、sparkle-design.css と SparkleHead.tsx を生成
 
 Check で検出する主なパターン:
   - フォーム入力に Dialog を使っている

package/lib/font-manager.js

@@ -66,7 +66,7 @@ function resolveNodeModulesRelPath(globalsPath) {
  * @returns {string} @source ディレクティブブロック
  */
 function createSourceBlock(sourcePackages = [], nodeModulesRel = '../node_modules') {
-  const defaultPackage = '@goodpatch/sparkle-design';
+  const defaultPackage = 'sparkle-design';
   const allPackages = [defaultPackage, ...sourcePackages.filter(p => p !== defaultPackage)];
   const sourceLines = allPackages.map(pkg => `@source "${nodeModulesRel}/${pkg}/dist";`);
   return [COMMENTS.SOURCE_DIRECTIVE, ...sourceLines].join('\n');

package/lib/setup.js

@@ -1,5 +1,49 @@
 import fs from 'fs';
 import path from 'path';
+import { spawnSync } from 'child_process';
+import { generateCSS } from './generate-css.js';
+
+// デフォルトの sparkle.config.json テンプレート
+// en: Default sparkle.config.json template
+const DEFAULT_SPARKLE_CONFIG = {
+  primary: 'blue',
+  'font-pro': 'Inter',
+  'font-mono': 'JetBrains Mono',
+  radius: 'md',
+};
+
+// 初期 globals.css のテンプレート
+// en: Initial globals.css template
+const INITIAL_GLOBALS_CSS = `@import "tailwindcss";
+@import "./sparkle-design.css";
+`;
+
+// インストール対象パッケージ
+// en: Packages to install
+const SPARKLE_PACKAGES = ['sparkle-design'];
+const TAILWIND_PACKAGES = ['tailwindcss', '@tailwindcss/postcss'];
+
+// 初期 postcss.config.mjs のテンプレート
+// en: Initial postcss.config.mjs template
+const INITIAL_POSTCSS_CONFIG = `/** @type {import('postcss-load-config').Config} */
+const config = {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+
+export default config;
+`;
+
+// globals.css 候補パス（優先順）
+// en: globals.css candidate paths in priority order
+const GLOBALS_CSS_CANDIDATES = [
+  'src/app/globals.css',
+  'app/globals.css',
+  'src/globals.css',
+  'src/index.css',
+  'src/styles/globals.css',
+];
 
 const ASSISTANT_CONFIG = {
   claude: {
@@ -27,10 +71,6 @@ function buildCheckScript(target, mode) {
 }
 
 
-function escapeRegExp(value) {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
 function ensureDir(filePath) {
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
 }
@@ -221,64 +261,213 @@ function updatePackageJson(filePath, target, force) {
   };
 }
 
-export function setupAssistant(options = {}) {
-  const assistant = options.assistant ?? 'generic';
-  const cwd = process.cwd();
-  const dryRun = Boolean(options.dryRun);
-  const force = Boolean(options.forceScriptUpdate);
-  const assistantConfig = ASSISTANT_CONFIG[assistant];
+// パッケージマネージャーごとの add サブコマンドと -D フラグ
+// en: Per-package-manager add subcommand and dev flag
+const PM_COMMANDS = {
+  pnpm: { add: 'add', dev: '-D' },
+  yarn: { add: 'add', dev: '-D' },
+  bun: { add: 'add', dev: '-d' },
+  npm: { add: 'install', dev: '--save-dev' },
+};
+
+/**
+ * パッケージマネージャーを lockfile から検出する
+ * en: Detect package manager from lock files
+ */
+function detectPackageManager(cwd) {
+  if (fs.existsSync(path.join(cwd, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (fs.existsSync(path.join(cwd, 'bun.lockb')) || fs.existsSync(path.join(cwd, 'bun.lock'))) return 'bun';
+  if (fs.existsSync(path.join(cwd, 'yarn.lock'))) return 'yarn';
+  return 'npm';
+}
+
+/**
+ * package.json に未登録のパッケージだけをインストールする
+ * en: Install only packages not yet listed in package.json
+ */
+function ensurePackagesInstalled(cwd, packageManager, candidates, { dev = false, dryRun = false } = {}) {
+  const packageJson = readJson(path.join(cwd, 'package.json'));
+  const deps = { ...(packageJson.dependencies ?? {}), ...(packageJson.devDependencies ?? {}) };
+  const missing = candidates.filter((pkg) => !Object.prototype.hasOwnProperty.call(deps, pkg));
 
-  if (!assistantConfig) {
-    throw new Error(`Unsupported assistant: ${assistant}`);
+  if (missing.length === 0) {
+    return { ran: false, reason: 'already-installed', packages: [] };
+  }
+  if (dryRun) {
+    return { ran: false, reason: 'dry-run', packages: missing, packageManager, dev };
   }
 
-  const targetSource = options.target ? 'explicit' : 'auto';
-  const target = options.target
-    ? normalizePath(cwd, options.target, 'Target path')
-    : normalizePath(cwd, detectTarget(cwd), 'Target path');
+  const pm = PM_COMMANDS[packageManager];
+  const args = [pm.add, ...(dev ? [pm.dev] : []), ...missing];
 
-  const packageJsonPath = path.resolve(cwd, 'package.json');
-  if (!fs.existsSync(packageJsonPath)) {
-    throw new Error(`package.json not found in ${cwd}`);
+  console.log(`📦 ${packageManager} ${args.join(' ')}`);
+  const result = spawnSync(packageManager, args, { cwd, stdio: 'inherit' });
+  if (result.status !== 0) {
+    throw new Error(`Failed to install packages via ${packageManager}: ${missing.join(', ')}`);
   }
 
+  return { ran: true, reason: 'installed', packages: missing, packageManager, dev };
+}
+
+/**
+ * src/app → src/app/globals.css、src 直下があれば src/globals.css を優先
+ * en: Prefer src/app/globals.css when src/app exists, otherwise src/globals.css
+ */
+function defaultGlobalsCssTarget(cwd) {
+  if (fs.existsSync(path.join(cwd, 'src/app'))) return 'src/app/globals.css';
+  if (fs.existsSync(path.join(cwd, 'src'))) return 'src/globals.css';
+  return 'src/app/globals.css';
+}
+
+// スキャフォールド対象のファイル定義
+// en: Scaffold targets: existing候補の1つでもヒットすれば作成をスキップ
+function buildScaffoldTargets(cwd) {
+  return [
+    {
+      name: 'sparkleConfig',
+      candidates: ['sparkle.config.json'],
+      target: 'sparkle.config.json',
+      write: (abs) => writeJson(abs, DEFAULT_SPARKLE_CONFIG),
+    },
+    {
+      name: 'postcssConfig',
+      candidates: ['postcss.config.mjs', 'postcss.config.js', 'postcss.config.cjs', 'postcss.config.ts'],
+      target: 'postcss.config.mjs',
+      write: (abs) => fs.writeFileSync(abs, INITIAL_POSTCSS_CONFIG, 'utf8'),
+    },
+    {
+      name: 'globalsCss',
+      candidates: GLOBALS_CSS_CANDIDATES,
+      target: defaultGlobalsCssTarget(cwd),
+      write: (abs) => {
+        ensureDir(abs);
+        fs.writeFileSync(abs, INITIAL_GLOBALS_CSS, 'utf8');
+      },
+    },
+  ];
+}
+
+/**
+ * 各スキャフォールド対象について、候補が1つでも存在すればスキップ、無ければ target に書き込む
+ * en: Scaffold each target: skip if any candidate exists, otherwise write to target
+ */
+function scaffoldAll(cwd, { dryRun = false } = {}) {
+  const results = {};
+  for (const spec of buildScaffoldTargets(cwd)) {
+    const existing = spec.candidates.find((c) => fs.existsSync(path.join(cwd, c)));
+    if (existing) {
+      results[spec.name] = { created: false, existed: true, path: existing };
+      continue;
+    }
+    if (!dryRun) spec.write(path.join(cwd, spec.target));
+    results[spec.name] = { created: true, existed: false, path: spec.target };
+  }
+  return results;
+}
+
+// --- パイプライン各フェーズ ---
+// en: Pipeline phases
+
+function runInstall(cwd, packageManager, { skipInstall, dryRun }) {
+  if (skipInstall) return { skipped: true, sparkle: null, tailwind: null };
+
+  console.log(`🔍 パッケージマネージャーを検出: ${packageManager}`);
+  return {
+    skipped: false,
+    sparkle: ensurePackagesInstalled(cwd, packageManager, SPARKLE_PACKAGES, { dryRun }),
+    tailwind: ensurePackagesInstalled(cwd, packageManager, TAILWIND_PACKAGES, { dev: true, dryRun }),
+  };
+}
+
+function runScaffold(cwd, { skipScaffold, dryRun }) {
+  if (skipScaffold) return { skipped: true };
+  return { skipped: false, ...scaffoldAll(cwd, { dryRun }) };
+}
+
+function runAssistantGuard(cwd, packageJsonPath, options, assistantConfig) {
+  const force = Boolean(options.forceScriptUpdate);
+  const target = options.target
+    ? normalizePath(cwd, options.target, 'Target path')
+    : normalizePath(cwd, detectTarget(cwd), 'Target path');
   const instructionPath = options.instructionsPath
     ? path.resolve(cwd, normalizePath(cwd, options.instructionsPath, 'Instructions path', { checkParentOnly: true }))
     : path.resolve(cwd, assistantConfig.path);
+
   const packageResult = updatePackageJson(packageJsonPath, target, force);
-  const instructionBlock = buildInstructionBlock(target, assistant);
+  const instructionBlock = buildInstructionBlock(target, options.assistant);
   const instructionResult = updateInstructionFile(instructionPath, instructionBlock);
 
-  if (!dryRun) {
-    if (packageResult.changed) {
-      writeJson(packageJsonPath, packageResult.packageJson);
-    }
-
+  if (!options.dryRun) {
+    if (packageResult.changed) writeJson(packageJsonPath, packageResult.packageJson);
     if (instructionResult.changed) {
       ensureDir(instructionPath);
       fs.writeFileSync(instructionPath, instructionResult.content, 'utf8');
     }
   }
 
+  return {
+    target,
+    targetSource: options.target ? 'explicit' : 'auto',
+    instructionPath,
+    packageResult,
+    instructionResult,
+  };
+}
+
+function runGenerate({ skipGenerate, dryRun }) {
+  if (skipGenerate || dryRun) return { skipped: true, ran: false };
+  try {
+    console.log('🎨 sparkle-design.css を生成中...');
+    generateCSS();
+    return { skipped: false, ran: true };
+  } catch (error) {
+    console.warn(`⚠️  generate 実行をスキップしました: ${error.message}`);
+    return { skipped: false, ran: false, error: error.message };
+  }
+}
+
+export function setupAssistant(options = {}) {
+  const assistant = options.assistant ?? 'generic';
+  const assistantConfig = ASSISTANT_CONFIG[assistant];
+  if (!assistantConfig) throw new Error(`Unsupported assistant: ${assistant}`);
+
+  const cwd = process.cwd();
+  const packageJsonPath = path.resolve(cwd, 'package.json');
+  if (!fs.existsSync(packageJsonPath)) {
+    throw new Error(`package.json not found in ${cwd}`);
+  }
+
+  const dryRun = Boolean(options.dryRun);
+  const packageManager = detectPackageManager(cwd);
+
+  const install = runInstall(cwd, packageManager, { skipInstall: Boolean(options.skipInstall), dryRun });
+  const scaffold = runScaffold(cwd, { skipScaffold: Boolean(options.skipScaffold), dryRun });
+  const guard = runAssistantGuard(cwd, packageJsonPath, { ...options, assistant, dryRun }, assistantConfig);
+  const generate = runGenerate({ skipGenerate: Boolean(options.skipGenerate), dryRun });
+
   const summary = {
     assistant,
-    target,
-    targetSource,
+    target: guard.target,
+    targetSource: guard.targetSource,
     dryRun,
-    forceScriptUpdate: force,
+    forceScriptUpdate: Boolean(options.forceScriptUpdate),
+    packageManager,
+    install,
+    scaffold,
+    generate,
     packageJson: {
       path: path.relative(cwd, packageJsonPath),
-      changed: packageResult.changed,
+      changed: guard.packageResult.changed,
       scripts: {
-        'lint:sparkle': packageResult.packageJson.scripts?.['lint:sparkle'] ?? null,
-        'lint:sparkle:json': packageResult.packageJson.scripts?.['lint:sparkle:json'] ?? null,
+        'lint:sparkle': guard.packageResult.packageJson.scripts?.['lint:sparkle'] ?? null,
+        'lint:sparkle:json': guard.packageResult.packageJson.scripts?.['lint:sparkle:json'] ?? null,
       },
-      results: packageResult.scriptResults,
+      results: guard.packageResult.scriptResults,
     },
     instructions: {
-      path: path.relative(cwd, instructionPath),
-      changed: instructionResult.changed,
-      existed: instructionResult.existed,
+      path: path.relative(cwd, guard.instructionPath),
+      changed: guard.instructionResult.changed,
+      existed: guard.instructionResult.existed,
     },
   };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparkle-design-cli",
-  "version": "1.6.2",
+  "version": "2.0.0",
   "description": "Sparkle Design CSS Generator - デザインシステムCSSを設定ファイルから生成するツール",
   "main": "lib/generate-css.js",
   "type": "module",