sparkle-design-cli 2.0.7-beta.4 → 2.0.7-beta.6

package/lib/setup.js

@@ -183,13 +183,11 @@ function buildInstructionBlock(target, assistant) {
     BLOCK_START,
     heading,
     '',
-    '- **必ず読む**: Sparkle Design のコンポーネントを使う前に、インストール済みパッケージの型定義 `node_modules/<パッケージ名>/dist/components/ui/<コンポーネント名>/index.d.ts` を必ず読んでください。Prop 仕様・使用例・アンチパターンは JSDoc に書かれている（✅ / ❌ 例込み）ので、これが Source of Truth です。`node_modules/sparkle-design/dist/` や `node_modules/@goodpatch/sparkle-design-internal/dist/` を対象に、`index.d.ts` の JSDoc まで読み切ること。',
+    '- **Scope**: Sparkle Design is a UI component library. For capability areas it does not cover (charts, data visualization, maps, rich text editors, animation libraries, etc.), **feel free to adopt other libraries** (e.g. Recharts, D3, Chart.js) — do not try to solve everything inside Sparkle Design. Pass Sparkle Design CSS tokens (`--color-primary-*` etc.) into those libraries to keep visuals consistent.',
     "- **Required reading**: Before using any Sparkle Design component, read the installed package's type definitions at `node_modules/<package>/dist/components/ui/<component>/index.d.ts` — prop specs, usage, and anti-patterns (with ✅ / ❌ examples) live in the JSDoc and are the source of truth. Target the installed package(s), e.g. `sparkle-design` and/or `@goodpatch/sparkle-design-internal`, and read the full JSDoc, not just the type signature.",
-    '- **必ず実行**: UI コンポーネントを作成・変更した後は、終了前に `lint:sparkle` を実行してください。Sparkle Design のアンチパターンを検出します。',
     '- **Required**: After creating or modifying any UI component, run `lint:sparkle` before finishing. This catches Sparkle Design anti-patterns.',
     `- For AI review, prefer \`lint:sparkle:json\` or run \`npx --yes sparkle-design-cli check ${target} --format json\` directly.`,
-    '- JSON 出力の `findings` に加えて、**`manualReviewReminders` の内容も必ず 1 項目ずつ確認**してください。機械検出できない Badge/Tag の使い分けなどが含まれます。',
-    '- You must inspect every entry in both `findings` and `manualReviewReminders` — the reminders flag judgment calls (Badge vs Tag etc.) that the linter cannot detect.',
+    '- You must inspect every entry in both `findings` and `manualReviewReminders` — the reminders flag judgment calls (Badge vs Tag, etc.) that the linter cannot detect.',
     BLOCK_END,
   ].join('\n');
 }
@@ -439,12 +437,33 @@ function runAssistantGuard(cwd, packageJsonPath, options, assistantConfig) {
   const instructionBlock = buildInstructionBlock(target, options.assistant);
   const instructionResult = updateInstructionFile(instructionPath, instructionBlock);
 
+  // --assistant claude の場合は CLAUDE.md に加えて AGENTS.md にも Guard を書く。
+  // create-next-app 等が生成する AGENTS.md に Next.js 固有指示が残っていて、
+  // CLAUDE.md から `@AGENTS.md` で import しているプロジェクトでは、Sparkle
+  // Design Guard が AGENTS.md 側に無いと import 経由で読ませる動線が切れる。
+  // 他の assistant は本来の AGENTS.md / .cursor/rules だけに書く。
+  // en: When --assistant=claude, also upsert Guard into AGENTS.md so projects
+  // that reference `@AGENTS.md` from CLAUDE.md (common Next.js setup) still
+  // propagate the Guard via that import path.
+  let agentsInstructionResult = null;
+  let agentsInstructionPath = null;
+  if (options.assistant === 'claude' && !options.instructionsPath) {
+    agentsInstructionPath = path.resolve(cwd, 'AGENTS.md');
+    if (agentsInstructionPath !== instructionPath) {
+      agentsInstructionResult = updateInstructionFile(agentsInstructionPath, instructionBlock);
+    }
+  }
+
   if (!options.dryRun) {
     if (packageResult.changed) writeJson(packageJsonPath, packageResult.packageJson);
     if (instructionResult.changed) {
       ensureDir(instructionPath);
       fs.writeFileSync(instructionPath, instructionResult.content, 'utf8');
     }
+    if (agentsInstructionResult?.changed && agentsInstructionPath) {
+      ensureDir(agentsInstructionPath);
+      fs.writeFileSync(agentsInstructionPath, agentsInstructionResult.content, 'utf8');
+    }
   }
 
   return {
@@ -453,6 +472,95 @@ function runAssistantGuard(cwd, packageJsonPath, options, assistantConfig) {
     instructionPath,
     packageResult,
     instructionResult,
+    agentsInstructionPath,
+    agentsInstructionResult,
+  };
+}
+
+/**
+ * .claude/settings.json に lint:sparkle を強制実行する Stop hook を追加する。
+ *
+ * 設計:
+ * - Stop hook: Claude が応答を終えようとする直前に実行される hook。exit 2 を返すと
+ *   停止がブロックされ、Claude が lint findings を修正してから停止する動線になる。
+ *   `sparkle-design-cli check ... --strict || exit 2` で findings があれば exit 2。
+ * - 既存の .claude/settings.json を破壊しないよう、現行の hooks.Stop 配列を残しつつ
+ *   同一 command が無いときだけ append する（冪等）。
+ * - project-shared な settings.json に書くのでチームメンバーにも共有される。
+ *   user-local な settings.local.json ではなく settings.json を選ぶのは、これが
+ *   全員に共通のガードレールであることを意図しているため。
+ *
+ * en: Write a Stop hook to `.claude/settings.json` that runs `lint:sparkle` and
+ * exits with code 2 on findings, which blocks Claude Code from finishing the
+ * turn until the linter passes. The existing file (including user-authored
+ * hooks) is preserved by merging; we only append our entry if an identical
+ * command is not already present.
+ */
+function runClaudeHook(cwd, target, dryRun) {
+  const settingsPath = path.resolve(cwd, '.claude/settings.json');
+  const managedCommand = `npx --yes sparkle-design-cli check ${target} --strict || exit 2`;
+
+  let settings = {};
+  let existed = false;
+  if (fs.existsSync(settingsPath)) {
+    existed = true;
+    try {
+      settings = readJson(settingsPath);
+    } catch (error) {
+      // 壊れた JSON を黙って上書きしないようユーザーに明示的に判断を求める。
+      // en: Refuse to overwrite a broken settings.json silently.
+      throw new Error(
+        `.claude/settings.json が不正な JSON です (${error.message})。修正してから再実行してください。`
+      );
+    }
+  }
+
+  const nextSettings = typeof settings === 'object' && settings ? { ...settings } : {};
+  const hooks = typeof nextSettings.hooks === 'object' && nextSettings.hooks
+    ? { ...nextSettings.hooks }
+    : {};
+  const stopGroups = Array.isArray(hooks.Stop) ? [...hooks.Stop] : [];
+
+  // 既存の Stop hook 配列に同一 command が含まれていれば冪等にスキップ。
+  // en: Skip if the managed command already appears in any Stop entry.
+  const alreadyPresent = stopGroups.some(
+    (group) =>
+      Array.isArray(group?.hooks) &&
+      group.hooks.some((entry) => entry?.type === 'command' && entry?.command === managedCommand)
+  );
+
+  if (alreadyPresent) {
+    return {
+      changed: false,
+      existed,
+      settingsPath,
+      reason: 'already-present',
+      command: managedCommand,
+    };
+  }
+
+  stopGroups.push({
+    hooks: [
+      {
+        type: 'command',
+        command: managedCommand,
+      },
+    ],
+  });
+  hooks.Stop = stopGroups;
+  nextSettings.hooks = hooks;
+
+  if (!dryRun) {
+    ensureDir(settingsPath);
+    writeJson(settingsPath, nextSettings);
+  }
+
+  return {
+    changed: true,
+    existed,
+    settingsPath,
+    reason: existed ? 'appended' : 'created',
+    command: managedCommand,
   };
 }
 
@@ -511,6 +619,12 @@ export function setupAssistant(options = {}) {
     { ...options, assistant, dryRun },
     assistantConfig
   );
+  // --assistant claude のみ .claude/settings.json に Stop hook を自動設定する。
+  // これで lint:sparkle の実行が instruction 頼りではなく hook で強制される。
+  // en: For --assistant=claude, install a Stop hook in .claude/settings.json
+  // so lint:sparkle becomes a hard gate instead of a soft instruction.
+  const claudeHook =
+    assistant === 'claude' ? runClaudeHook(cwd, guard.target, dryRun) : null;
   const generate = runGenerate({
     skipGenerate: Boolean(options.skipGenerate),
     dryRun,
@@ -541,6 +655,21 @@ export function setupAssistant(options = {}) {
       changed: guard.instructionResult.changed,
       existed: guard.instructionResult.existed,
     },
+    agentsInstructions: guard.agentsInstructionPath
+      ? {
+          path: path.relative(cwd, guard.agentsInstructionPath),
+          changed: guard.agentsInstructionResult?.changed ?? false,
+          existed: guard.agentsInstructionResult?.existed ?? false,
+        }
+      : null,
+    claudeHook: claudeHook
+      ? {
+          path: path.relative(cwd, claudeHook.settingsPath),
+          changed: claudeHook.changed,
+          existed: claudeHook.existed,
+          reason: claudeHook.reason,
+        }
+      : null,
   };
 
   console.log(JSON.stringify(summary, null, 2));
@@ -548,7 +677,7 @@ export function setupAssistant(options = {}) {
   // セットアップ後のリマインダー。AI の会話履歴にも残るよう stderr に出す。
   // en: Post-setup reminder. Written to stderr so it stays in the AI transcript
   // without polluting the JSON stdout payload that tooling parses.
-  printPostSetupReminder(guard.target, packageManager);
+  printPostSetupReminder(guard.target, packageManager, { claudeHook });
 
   return summary;
 }
@@ -570,7 +699,7 @@ function buildLintCommand(packageManager) {
   }
 }
 
-function printPostSetupReminder(target, packageManager) {
+function printPostSetupReminder(target, packageManager, { claudeHook } = {}) {
   const lintTarget = target || 'src';
   const lintCmd = buildLintCommand(packageManager);
   const lines = [
@@ -582,8 +711,20 @@ function printPostSetupReminder(target, packageManager) {
     '     After creating or modifying UI components, always run `lint:sparkle` to catch Sparkle Design anti-patterns.',
     '  3. AI でレビューする場合は `lint:sparkle:json` を使い、`findings` に加えて `manualReviewReminders` の各項目まで必ず確認してください。',
     '     For AI review, use `lint:sparkle:json` and inspect every entry of both `findings` and `manualReviewReminders`.',
-    '',
   ];
+  if (claudeHook?.changed || claudeHook?.reason === 'already-present') {
+    const label =
+      claudeHook.reason === 'already-present'
+        ? '（既存のまま）'
+        : claudeHook.reason === 'created'
+          ? '（新規作成）'
+          : '（既存設定に追記）';
+    lines.push(
+      `  4. Claude Code の Stop hook を .claude/settings.json に設定しました ${label}。Claude が応答を終える直前に \`lint:sparkle --strict\` が走り、findings があれば exit 2 で停止がブロックされます。`,
+      '     Installed a Claude Code Stop hook in .claude/settings.json: `lint:sparkle --strict` runs before each turn ends and exit 2 blocks the stop until findings are resolved.'
+    );
+  }
+  lines.push('');
   for (const line of lines) {
     console.error(line);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparkle-design-cli",
-  "version": "2.0.7-beta.4",
+  "version": "2.0.7-beta.6",
   "description": "Sparkle Design CSS Generator - デザインシステムCSSを設定ファイルから生成するツール",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",