sparkle-design-cli 2.0.7-rc.4 → 2.0.8

package/bin/sparkle-design.js

@@ -3,8 +3,9 @@
 import { generateCSS } from '../lib/generate-css.js';
 import { checkProject } from '../lib/check.js';
 import { setupAssistant } from '../lib/setup.js';
+import { runStopHook } from '../lib/stop-hook.js';
 
-const SUBCOMMANDS = new Set(['generate', 'check', 'setup']);
+const SUBCOMMANDS = new Set(['generate', 'check', 'setup', 'stop-hook']);
 
 function requireOptionValue(args, index, flags) {
   const value = args[index + 1];
@@ -138,6 +139,7 @@ Commands:
   generate   sparkle.config.json から CSS を生成
   check      Sparkle Design のアンチパターンを検査
   setup      Sparkle Design プロジェクトをセットアップ（パッケージ導入 + 初期ファイル + AI ガード + generate）
+  stop-hook  AI assistant の Stop hook 用 internal subcommand（findings 検出時に exit 2 で 1 度だけ停止をブロック / 再発火は自動回避）
 
 Generate:
   sparkle-design-cli generate
@@ -302,6 +304,16 @@ function main() {
       return;
     }
 
+    if (command === 'stop-hook') {
+      // setup で各 agent の hook 設定ファイルから呼ばれる internal subcommand。
+      // 第 2 引数は lint 対象 path（setup 時に決まったもの）。option flag は未対応。
+      // en: Internal subcommand invoked by agent stop hooks. The single positional
+      // arg is the lint target path determined at setup time.
+      const target = args[1];
+      const exitCode = runStopHook(target);
+      process.exit(exitCode);
+    }
+
     // 未知のコマンド: エラー終了ではなく note + help 表示にする（typo 時の迷子を防ぐ）
     // en: Unknown command: show a short note + help instead of throwing
     console.warn(

package/lib/setup.js

@@ -594,16 +594,20 @@ function runAssistantGuard(cwd, packageJsonPath, options, assistantConfig) {
  *
  * 各 agent が持つ hook システムの schema は異なるため、agent ごとに以下の
  * ヘルパーを持つ。共通ポイントは:
- *   - 実行コマンドは `npx --yes sparkle-design-cli check <target> --strict || exit 2`
- *   - exit 2 にエスカレーションすることで、ブロック対応する agent では
- *     応答終了を止めて findings 修正に向かわせる
+ *   - 実行コマンドは `npx --yes sparkle-design-cli stop-hook <target>`
+ *     （内部で check --strict を回し、初回 findings 検出時のみ exit 2 で停止を
+ *     ブロックする。Claude Code の `stop_hook_active` を読んで再発火時は
+ *     exit 0 で抜けることでセッション内ループを防ぐ）
  *   - 既存の hook 設定ファイルは非破壊マージし、同一 command が含まれていれば skip
- *     （冪等）
+ *     （冪等）。2.0.7 までの旧コマンド `check ... --strict || exit 2` を見つけたら
+ *     新 subcommand へ自動移行する
  *   - 壊れた JSON は silent 上書きせず、ユーザーに修正を促すエラーを出す
  *
- * en: Install an agent-specific hook that runs `lint:sparkle --strict || exit 2`.
- * Each agent ships its own hook config format; these helpers emit the right
- * shape while preserving existing user content and staying idempotent on rerun.
+ * en: Install an agent-specific hook that runs the `stop-hook` subcommand,
+ * which surfaces findings once and avoids the infinite re-fire loop the
+ * pre-2.0.8 form had. Each agent ships its own hook config format; these
+ * helpers emit the right shape, stay idempotent on rerun, and migrate
+ * legacy 2.0.7 commands when found.
  *
  * References (2026-04 時点):
  *   - Claude Code : https://docs.claude.com/en/docs/claude-code/hooks
@@ -611,7 +615,26 @@ function runAssistantGuard(cwd, packageJsonPath, options, assistantConfig) {
  *   - Codex       : https://developers.openai.com/codex/hooks
  */
 function buildManagedHookCommand(target) {
-  return `npx --yes sparkle-design-cli check ${target} --strict || exit 2`;
+  // Stop / stop hook は専用 subcommand に集約する。subcommand 側で
+  // `stop_hook_active` を見て初回だけ exit 2、再発火時は exit 0 で抜ける
+  // ことでセッション内ループを防ぐ。
+  // en: Route through the dedicated `stop-hook` subcommand so we can detect
+  // re-fires (Claude Code's `stop_hook_active`) and avoid infinite loops.
+  return `npx --yes sparkle-design-cli stop-hook ${target}`;
+}
+
+/**
+ * 2.0.7 までは `npx --yes sparkle-design-cli check <target> --strict || exit 2` を
+ * 直接 hook に書いていたが、findings が残っていると Stop hook が再発火し続けて
+ * セッションが無限ループする問題があった。`stop-hook` subcommand に切り替える
+ * ため、既存 hook 設定にこの旧コマンドが残っている場合は新コマンドへ置換する。
+ *
+ * en: Detect legacy hook commands installed by 2.0.7 and earlier so setup
+ * reruns can heal them by swapping in the loop-safe `stop-hook` subcommand.
+ */
+function isLegacyManagedHookCommand(command) {
+  if (typeof command !== 'string') return false;
+  return /sparkle-design-cli\s+check\s+\S+\s+--strict\s*\|\|\s*exit\s+2/.test(command);
 }
 
 function loadHookJson(filePath, label) {
@@ -685,14 +708,40 @@ function runClaudeHook(cwd, target, dryRun) {
     typeof nextSettings.hooks === 'object' && nextSettings.hooks ? { ...nextSettings.hooks } : {};
   const stopGroups = Array.isArray(hooks.Stop) ? [...hooks.Stop] : [];
 
-  const alreadyPresent = stopGroups.some(
-    (group) =>
-      Array.isArray(group?.hooks) &&
-      group.hooks.some((entry) => entry?.type === 'command' && entry?.command === managedCommand)
-  );
+  // 1st pass: legacy エントリを発見。alreadyPresent / migrated を判定する。
+  // 2 回目以降の setup や、ユーザーが手動で新コマンドを足した状態でも
+  // 重複が出ないよう、変換は 2nd pass で行う。
+  // en: First pass detects state; second pass mutates without creating dupes.
+  let alreadyPresent = false;
+  let hasLegacy = false;
+  for (const group of stopGroups) {
+    if (!Array.isArray(group?.hooks)) continue;
+    for (const entry of group.hooks) {
+      if (entry?.type !== 'command') continue;
+      if (entry.command === managedCommand) alreadyPresent = true;
+      else if (isLegacyManagedHookCommand(entry.command)) hasLegacy = true;
+    }
+  }
+  const migrated = hasLegacy;
+
+  const updatedGroups = stopGroups.map((group) => {
+    if (!Array.isArray(group?.hooks)) return group;
+    const updatedHooks = group.hooks
+      .map((entry) => {
+        if (entry?.type === 'command' && isLegacyManagedHookCommand(entry.command)) {
+          // legacy + 新コマンドが両方あったら legacy を削除（dedupe）。
+          // legacy のみなら新コマンドへ in-place 置換。
+          // en: Drop legacy when the new command coexists; otherwise rewrite.
+          return alreadyPresent ? null : { ...entry, command: managedCommand };
+        }
+        return entry;
+      })
+      .filter((entry) => entry !== null);
+    return { ...group, hooks: updatedHooks };
+  });
 
   const mismatch = detectClaudeSessionRootMismatch(cwd);
-  if (alreadyPresent) {
+  if (alreadyPresent && !migrated) {
     return {
       assistant: 'claude',
       changed: false,
@@ -704,10 +753,12 @@ function runClaudeHook(cwd, target, dryRun) {
     };
   }
 
-  stopGroups.push({
-    hooks: [{ type: 'command', command: managedCommand }],
-  });
-  hooks.Stop = stopGroups;
+  let nextStopGroups = updatedGroups;
+  if (!migrated && !alreadyPresent) {
+    nextStopGroups = [...updatedGroups, { hooks: [{ type: 'command', command: managedCommand }] }];
+  }
+
+  hooks.Stop = nextStopGroups;
   nextSettings.hooks = hooks;
 
   if (!dryRun) {
@@ -719,7 +770,7 @@ function runClaudeHook(cwd, target, dryRun) {
     changed: true,
     existed,
     path: settingsPath,
-    reason: existed ? 'appended' : 'created',
+    reason: migrated ? 'migrated' : existed ? 'appended' : 'created',
     command: managedCommand,
     sessionRootMismatch: mismatch,
   };
@@ -740,8 +791,24 @@ function runCursorHook(cwd, target, dryRun) {
     typeof nextConfig.hooks === 'object' && nextConfig.hooks ? { ...nextConfig.hooks } : {};
   const stopEntries = Array.isArray(hooks.stop) ? [...hooks.stop] : [];
 
-  const alreadyPresent = stopEntries.some((entry) => entry?.command === managedCommand);
-  if (alreadyPresent) {
+  let alreadyPresent = false;
+  let hasLegacy = false;
+  for (const entry of stopEntries) {
+    if (entry?.command === managedCommand) alreadyPresent = true;
+    else if (isLegacyManagedHookCommand(entry?.command)) hasLegacy = true;
+  }
+  const migrated = hasLegacy;
+
+  const updatedEntries = stopEntries
+    .map((entry) => {
+      if (isLegacyManagedHookCommand(entry?.command)) {
+        return alreadyPresent ? null : { ...entry, command: managedCommand };
+      }
+      return entry;
+    })
+    .filter((entry) => entry !== null);
+
+  if (alreadyPresent && !migrated) {
     return {
       assistant: 'cursor',
       changed: false,
@@ -752,8 +819,12 @@ function runCursorHook(cwd, target, dryRun) {
     };
   }
 
-  stopEntries.push({ command: managedCommand });
-  hooks.stop = stopEntries;
+  let nextStopEntries = updatedEntries;
+  if (!migrated && !alreadyPresent) {
+    nextStopEntries = [...updatedEntries, { command: managedCommand }];
+  }
+
+  hooks.stop = nextStopEntries;
   nextConfig.hooks = hooks;
 
   if (!dryRun) {
@@ -766,7 +837,7 @@ function runCursorHook(cwd, target, dryRun) {
     changed: true,
     existed,
     path: hooksPath,
-    reason: existed ? 'appended' : 'created',
+    reason: migrated ? 'migrated' : existed ? 'appended' : 'created',
     command: managedCommand,
   };
 }
@@ -786,13 +857,37 @@ function runCodexHook(cwd, target, dryRun) {
     typeof nextConfig.hooks === 'object' && nextConfig.hooks ? { ...nextConfig.hooks } : {};
   const stopGroups = Array.isArray(hooks.Stop) ? [...hooks.Stop] : [];
 
-  const alreadyPresent = stopGroups.some(
-    (group) =>
-      Array.isArray(group?.hooks) &&
-      group.hooks.some((entry) => entry?.type === 'command' && entry?.command === managedCommand)
-  );
+  let alreadyPresent = false;
+  let hasLegacy = false;
+  for (const group of stopGroups) {
+    if (!Array.isArray(group?.hooks)) continue;
+    for (const entry of group.hooks) {
+      if (entry?.type !== 'command') continue;
+      if (entry.command === managedCommand) alreadyPresent = true;
+      else if (isLegacyManagedHookCommand(entry.command)) hasLegacy = true;
+    }
+  }
+  const migrated = hasLegacy;
+
+  const updatedGroups = stopGroups.map((group) => {
+    if (!Array.isArray(group?.hooks)) return group;
+    const updatedHooks = group.hooks
+      .map((entry) => {
+        if (entry?.type === 'command' && isLegacyManagedHookCommand(entry.command)) {
+          return alreadyPresent ? null : { ...entry, command: managedCommand };
+        }
+        return entry;
+      })
+      .filter((entry) => entry !== null);
+    return { ...group, hooks: updatedHooks };
+  });
+
+  // 有効化にはユーザー側の opt-in が必要な旨を summary に載せる。
+  // en: Codex hooks are behind an opt-in feature flag; surface that in summary.
+  const featureFlagNote =
+    'Codex で有効化するには `~/.codex/config.toml` に `[features]` セクションを作り `codex_hooks = true` を設定してください。';
 
-  if (alreadyPresent) {
+  if (alreadyPresent && !migrated) {
     return {
       assistant: 'codex',
       changed: false,
@@ -800,17 +895,16 @@ function runCodexHook(cwd, target, dryRun) {
       path: hooksPath,
       reason: 'already-present',
       command: managedCommand,
-      // 有効化にはユーザー側の opt-in が必要な旨を summary に載せる。
-      // en: Codex hooks are behind an opt-in feature flag; surface that in summary.
-      featureFlagNote:
-        'Codex で有効化するには `~/.codex/config.toml` に `[features]` セクションを作り `codex_hooks = true` を設定してください。',
+      featureFlagNote,
     };
   }
 
-  stopGroups.push({
-    hooks: [{ type: 'command', command: managedCommand }],
-  });
-  hooks.Stop = stopGroups;
+  let nextStopGroups = updatedGroups;
+  if (!migrated && !alreadyPresent) {
+    nextStopGroups = [...updatedGroups, { hooks: [{ type: 'command', command: managedCommand }] }];
+  }
+
+  hooks.Stop = nextStopGroups;
   nextConfig.hooks = hooks;
 
   if (!dryRun) {
@@ -823,10 +917,9 @@ function runCodexHook(cwd, target, dryRun) {
     changed: true,
     existed,
     path: hooksPath,
-    reason: existed ? 'appended' : 'created',
+    reason: migrated ? 'migrated' : existed ? 'appended' : 'created',
     command: managedCommand,
-    featureFlagNote:
-      'Codex で有効化するには `~/.codex/config.toml` に `[features]` セクションを作り `codex_hooks = true` を設定してください。',
+    featureFlagNote,
   };
 }
 
@@ -918,11 +1011,12 @@ export function setupAssistant(options = {}) {
     assistantConfig
   );
   // assistant 別に hook 設定ファイル（`.claude/settings.json` /
-  // `.cursor/hooks.json` / `.codex/hooks.json`）に `lint:sparkle --strict` を
-  // 走らせる stop / Stop hook を自動設定する。instruction 頼みではなく hook
-  // で強制することで lint:sparkle の実行漏れを防ぐ。generic は hook なし。
-  // en: For supported assistants, install a stop hook so `lint:sparkle --strict`
-  // becomes a hard gate. Generic assistant has no hook target.
+  // `.cursor/hooks.json` / `.codex/hooks.json`）に `stop-hook` subcommand を
+  // 設定する。instruction 頼みではなく hook で強制することで lint:sparkle の
+  // 実行漏れを防ぐ。subcommand 側で `stop_hook_active` を見て再発火を抑止し、
+  // findings があるときの 1 回だけ exit 2 でブロックする。generic は hook なし。
+  // en: Install the loop-safe `stop-hook` subcommand so lint:sparkle becomes a
+  // hard gate. Generic assistant has no hook target.
   const hook = runAssistantHook(assistant, cwd, guard.target, dryRun);
   const generate = runGenerate({
     skipGenerate: Boolean(options.skipGenerate),
@@ -1045,10 +1139,12 @@ function printPostSetupReminder(target, packageManager, { hook, legacyCursorGuar
         ? '（既存のまま）'
         : hook.reason === 'created'
           ? '（新規作成）'
-          : '（既存設定に追記）';
+          : hook.reason === 'migrated'
+            ? '（旧 || exit 2 形式から自動移行）'
+            : '（既存設定に追記）';
     lines.push(
-      `  4. ${meta.name} の ${meta.event} hook を ${meta.file} に設定しました ${label}。応答を終える直前に \`lint:sparkle --strict\` が走り、findings があれば exit 2 で停止がブロックされます。`,
-      `     Installed a ${meta.name} ${meta.event} hook in ${meta.file}: it runs \`lint:sparkle --strict\` before the turn ends and exits with code 2 when findings exist.`
+      `  4. ${meta.name} の ${meta.event} hook を ${meta.file} に設定しました ${label}。応答を終える直前に \`sparkle-design-cli stop-hook\` が走り、findings があれば 1 度だけ exit 2 で停止をブロックします（再発火は \`stop_hook_active\` を見て自動回避）。`,
+      `     Installed a ${meta.name} ${meta.event} hook in ${meta.file}: it runs \`sparkle-design-cli stop-hook\` before the turn ends, blocks once with exit 2 when findings exist, and skips re-blocking on stop_hook_active.`
     );
     if (hook.featureFlagNote) {
       lines.push(`     ⚠️  ${hook.featureFlagNote}`);

package/lib/stop-hook.js

@@ -0,0 +1,60 @@
+import fs from 'fs';
+import { checkProject } from './check.js';
+
+/**
+ * AI assistant の Stop / stop hook 用エントリポイント。
+ *
+ * 単に `lint:sparkle --strict || exit 2` を毎回走らせると、Claude Code
+ * のように exit 2 を「もう一度ターンを継続させる」シグナルとして解釈する
+ * agent では、findings が残っている限り Stop hook が再発火し続けて
+ * セッションが無限ループに陥る。
+ *
+ * Claude Code は再発火時に stdin JSON へ `stop_hook_active: true` を
+ * 渡してくるので、そのフラグが立っていたらここで block せず exit 0 で
+ * 抜ける。これで「最初の 1 回だけ exit 2 で停止をブロックして findings
+ * を通知し、以降はユーザーの判断に委ねる」フローになる。
+ *
+ * en: Run `check --strict` once per session to surface findings, but stop
+ * blocking on subsequent invocations within the same Stop hook chain.
+ * Claude Code sets `stop_hook_active: true` on re-fires so the hook can
+ * exit cleanly instead of looping forever (see Claude Code hooks docs).
+ */
+export function runStopHook(target) {
+  const payload = readStdinJsonSafely();
+
+  if (payload && payload.stop_hook_active === true) {
+    process.stderr.write(
+      'sparkle-design-cli stop-hook: stop_hook_active=true を検知したため再ブロックしません。' +
+        '前回の exit 2 で findings は通知済みです。' +
+        ' / Detected stop_hook_active=true; not re-blocking. Findings were already surfaced on the first call.\n'
+    );
+    return 0;
+  }
+
+  const targets = target ? [target] : [];
+  const hasFindings = checkProject(targets, { strict: true, format: 'text' });
+
+  if (hasFindings) {
+    process.stderr.write(
+      '\nsparkle-design-cli stop-hook: findings を検出したため応答終了を 1 度だけブロックしました。' +
+        '上記の findings を修正するか、対応しない判断であればユーザーに確認してから再度応答を完了してください。' +
+        ' / Blocked once because findings were detected. Fix them or confirm with the user before completing the response again.\n'
+    );
+    return 2;
+  }
+
+  return 0;
+}
+
+function readStdinJsonSafely() {
+  // stdin が tty / 空 / 非 JSON の場合は「初回呼び出し」として扱う。
+  // en: Treat missing or non-JSON stdin as a first invocation.
+  try {
+    if (process.stdin.isTTY) return null;
+    const raw = fs.readFileSync(0, 'utf8');
+    if (!raw || !raw.trim()) return null;
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparkle-design-cli",
-  "version": "2.0.7-rc.4",
+  "version": "2.0.8",
   "description": "Sparkle Design CLI — プロジェクトセットアップ、CSS・フォント生成、アンチパターン検査、AI エージェント（Claude Code / Cursor / Codex）向けのガードと hook 設定まで一括で行う sparkle-design 公式 CLI。",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",