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

package/README.md

@@ -24,11 +24,11 @@ npm install -g sparkle-design-cli
 
 npm の dist-tag でチャネルを分けています。通常は `latest` を使い、RC や beta は先行試用時のみ指定してください。
 
-| チャネル | dist-tag | バージョン形式 | 用途 |
-| --- | --- | --- | --- |
-| 安定版 | `latest` | `X.Y.Z` | 本番運用向け（デフォルト） |
-| Release Candidate | `next` | `X.Y.Z-rc.N` | GA 直前の検証、チーム展開前 |
-| Beta | `beta` | `X.Y.Z-beta.N` | 品質保証中の検証用 |
+| チャネル          | dist-tag | バージョン形式 | 用途                        |
+| ----------------- | -------- | -------------- | --------------------------- |
+| 安定版            | `latest` | `X.Y.Z`        | 本番運用向け（デフォルト）  |
+| Release Candidate | `next`   | `X.Y.Z-rc.N`   | GA 直前の検証、チーム展開前 |
+| Beta              | `beta`   | `X.Y.Z-beta.N` | 品質保証中の検証用          |
 
 ```bash
 # latest を使う（デフォルト）
@@ -203,7 +203,7 @@ npx --yes sparkle-design-cli setup --assistant claude --skip-install --skip-scaf
 
 - `claude`: `CLAUDE.md`
 - `codex`: `AGENTS.md`
-- `cursor`: `.cursor/rules/sparkle-design-guard.mdc`
+- `cursor`: `AGENTS.md`（rc.4 から `.cursor/rules/*.mdc` を廃止。Cursor は AGENTS.md を always-load するため、条件付き読み込みで Guard が silent に skip される問題を解消）
 - `generic`: `SPARKLE-DESIGN-AI.md`
 
 #### setup オプション一覧
@@ -291,10 +291,19 @@ Next.js / Vite 以外ではアプリケーションフレームワークごと
 ```html
 <link rel="preconnect" href="https://fonts.googleapis.com" />
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
-<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Rounded:FILL,wght@0..1,500&display=block" />
+<link
+  rel="stylesheet"
+  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Rounded:FILL,wght@0..1,500&display=block"
+/>
 <!-- sparkle.config.json の font-pro / font-mono に合わせた Google Fonts URL -->
-<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap" />
-<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;700&display=swap" />
+<link
+  rel="stylesheet"
+  href="https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap"
+/>
+<link
+  rel="stylesheet"
+  href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;700&display=swap"
+/>
 ```
 
 **7. アンチパターン検査を package.json に追加（任意）**
@@ -310,7 +319,7 @@ Next.js / Vite 以外ではアプリケーションフレームワークごと
 
 **8. AI エージェントを使うなら Guard ブロックと hook を手動で配置**
 
-AI ガード（`CLAUDE.md` / `AGENTS.md` / `.cursor/rules/*.mdc`）と hook 設定（`.claude/settings.json` / `.cursor/hooks.json` / `.codex/hooks.json`）は `setup` に任せるのが最も楽です。
+AI ガード（`CLAUDE.md` / `AGENTS.md`）と hook 設定（`.claude/settings.json` / `.cursor/hooks.json` / `.codex/hooks.json`）は `setup` に任せるのが最も楽です。Cursor 用 Guard は rc.4 から AGENTS.md に統一しました（`.cursor/rules/*.mdc` は条件付き読み込みのため）。
 
 ```bash
 # ガード追加・hook 設定のみ（パッケージインストールや scaffold はスキップ）

package/lib/setup.js

@@ -56,6 +56,15 @@ const config = {
 export default config;
 `;
 
+// Guard ブロックは「常に読まれる」ファイルだけに置く。Cursor は 2025 年後半
+// 以降 AGENTS.md を公式サポートしている（https://agents.md）ので、
+// `.cursor/rules/*.mdc`（frontmatter で `alwaysApply: true` を付けない限り
+// 条件付き読み込み）は使わない。条件付き読み込みは Guard が読まれない
+// セッションで silent に lint:sparkle 実行漏れを起こす。
+// en: Keep Guard on always-loaded files. `.cursor/rules/*.mdc` is loaded
+// conditionally unless `alwaysApply: true` is set in frontmatter, which
+// silently skips the Guard in some sessions. Cursor (Codex / Aider / Zed
+// / Gemini CLI etc.) all read AGENTS.md, so route Cursor through it.
 const ASSISTANT_CONFIG = {
   claude: {
     path: 'CLAUDE.md',
@@ -64,13 +73,20 @@ const ASSISTANT_CONFIG = {
     path: 'AGENTS.md',
   },
   cursor: {
-    path: '.cursor/rules/sparkle-design-guard.mdc',
+    path: 'AGENTS.md',
   },
   generic: {
     path: 'SPARKLE-DESIGN-AI.md',
   },
 };
 
+// 旧版（rc.3 以前）が cursor 用に書いていた `.mdc` パス。残骸を検出して
+// AGENTS.md への移行を促す warn に使う。silent 削除はしない（ユーザーが
+// frontmatter を付けて意図的に保持しているケースもあるため）。
+// en: Path used by rc.3 and earlier for cursor assistant. We keep it as a
+// constant so the migration warn can detect leftovers without re-typing.
+const LEGACY_CURSOR_GUARD_PATH = '.cursor/rules/sparkle-design-guard.mdc';
+
 const BLOCK_START = '<!-- sparkle-design-cli:setup:start -->';
 const BLOCK_END = '<!-- sparkle-design-cli:setup:end -->';
 const TARGET_CANDIDATES = ['src', 'src/components', 'src/features', 'app', 'components'];
@@ -206,8 +222,14 @@ function isManagedSparkleScript(value, mode) {
   return false;
 }
 
-function buildInstructionBlock(target, assistant) {
-  const heading = assistant === 'cursor' ? '# Sparkle Design Guard' : '## Sparkle Design Guard';
+function buildInstructionBlock(target, _assistant) {
+  // Guard ブロックは常に h2 で出す。rc.3 以前は cursor 用に独立 .mdc ファイル
+  // へ書いていたため h1 にしていたが、rc.4 で AGENTS.md に統一したため、
+  // 親ファイルの heading 階層に揃えて h2 が常に正しい。
+  // en: Always emit Guard as h2. rc.3 used h1 for the standalone cursor
+  // .mdc file, but rc.4 routes cursor through AGENTS.md so h2 fits the
+  // surrounding section hierarchy.
+  const heading = '## Sparkle Design Guard';
 
   return [
     BLOCK_START,
@@ -243,10 +265,7 @@ function updateInstructionFile(filePath, block) {
         `⚠️  ${filePath} に Sparkle Design Guard ブロックが ${markerCount} 個見つかりました。すべて最新版で置き換えます（手動でコピーした古い block が残っている可能性があります）。`
       );
     }
-    const next = current.replace(
-      new RegExp(`${BLOCK_START}[\\s\\S]*?${BLOCK_END}`, 'g'),
-      block
-    );
+    const next = current.replace(new RegExp(`${BLOCK_START}[\\s\\S]*?${BLOCK_END}`, 'g'), block);
     return { changed: next !== current, content: next, existed: exists };
   }
 
@@ -510,6 +529,42 @@ function runAssistantGuard(cwd, packageJsonPath, options, assistantConfig) {
     }
   }
 
+  // rc.4 で Cursor の Guard 出力先を `.cursor/rules/sparkle-design-guard.mdc`
+  // から AGENTS.md に移したため、再 setup 時に旧 .mdc が残っているとガードが
+  // 二重定義になる（しかも .mdc は frontmatter 次第で読まれない場合がある）。
+  // silent 削除はせず、警告だけ出して移行判断はユーザーに委ねる。Cursor 以外
+  // のアシスタントでも、過去に cursor → 別 assistant に切り替えたユーザーが
+  // いるので assistant 値に関係なくチェックする。
+  // en: rc.4 moved Cursor Guard from `.cursor/rules/*.mdc` to AGENTS.md.
+  // Detect leftovers and warn the user instead of deleting silently — the
+  // .mdc may still be intentionally retained with `alwaysApply: true`.
+  let legacyCursorGuard = null;
+  if (!options.instructionsPath) {
+    const legacyPath = path.resolve(cwd, LEGACY_CURSOR_GUARD_PATH);
+    if (fs.existsSync(legacyPath)) {
+      try {
+        const content = fs.readFileSync(legacyPath, 'utf8');
+        // BLOCK_START だけでなく BLOCK_END も含み、かつ START が END より
+        // 前にある完全な block の場合のみ legacy 判定する。途中で削れた断片や
+        // ユーザーが手動でコピーした start マーカーだけ残っているケースを
+        // legacy 警告対象から外す（false positive 防止）。
+        // en: Require both markers in the correct order so partial fragments
+        // don't trigger the migration warn.
+        const startIndex = content.indexOf(BLOCK_START);
+        const endIndex = content.indexOf(BLOCK_END);
+        if (startIndex !== -1 && endIndex !== -1 && startIndex < endIndex) {
+          legacyCursorGuard = { path: legacyPath };
+        }
+      } catch (error) {
+        // 読み込み失敗（権限等）は legacy 検知だけスキップ。setup 本体は続行。
+        // en: Skip legacy detection on read failure; do not block setup.
+        console.warn(
+          `⚠️  ${LEGACY_CURSOR_GUARD_PATH} の読み込みに失敗したため legacy ガード検出をスキップします (${error.code ?? error.message})`
+        );
+      }
+    }
+  }
+
   if (!options.dryRun) {
     if (packageResult.changed) writeJson(packageJsonPath, packageResult.packageJson);
     if (instructionResult.changed) {
@@ -530,6 +585,7 @@ function runAssistantGuard(cwd, packageJsonPath, options, assistantConfig) {
     instructionResult,
     agentsInstructionPath,
     agentsInstructionResult,
+    legacyCursorGuard,
   };
 }
 
@@ -624,12 +680,9 @@ function runClaudeHook(cwd, target, dryRun) {
   const managedCommand = buildManagedHookCommand(target);
   const { existed, config } = loadHookJson(settingsPath, '.claude/settings.json');
 
-  const nextSettings =
-    typeof config === 'object' && config ? { ...config } : {};
+  const nextSettings = typeof config === 'object' && config ? { ...config } : {};
   const hooks =
-    typeof nextSettings.hooks === 'object' && nextSettings.hooks
-      ? { ...nextSettings.hooks }
-      : {};
+    typeof nextSettings.hooks === 'object' && nextSettings.hooks ? { ...nextSettings.hooks } : {};
   const stopGroups = Array.isArray(hooks.Stop) ? [...hooks.Stop] : [];
 
   const alreadyPresent = stopGroups.some(
@@ -908,6 +961,11 @@ export function setupAssistant(options = {}) {
           existed: guard.agentsInstructionResult?.existed ?? false,
         }
       : null,
+    legacyCursorGuard: guard.legacyCursorGuard
+      ? {
+          path: path.relative(cwd, guard.legacyCursorGuard.path),
+        }
+      : null,
     hook: hook
       ? {
           assistant: hook.assistant,
@@ -924,8 +982,7 @@ export function setupAssistant(options = {}) {
           sessionRootMismatch: hook.sessionRootMismatch
             ? {
                 detected: true,
-                sessionDir: path.relative(cwd, hook.sessionRootMismatch.sessionDir) ||
-                  '.',
+                sessionDir: path.relative(cwd, hook.sessionRootMismatch.sessionDir) || '.',
               }
             : null,
         }
@@ -937,7 +994,10 @@ 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, { hook });
+  printPostSetupReminder(guard.target, packageManager, {
+    hook,
+    legacyCursorGuard: guard.legacyCursorGuard,
+  });
 
   return summary;
 }
@@ -965,7 +1025,7 @@ const HOOK_LABELS = {
   codex: { name: 'Codex', file: '.codex/hooks.json', event: 'Stop' },
 };
 
-function printPostSetupReminder(target, packageManager, { hook } = {}) {
+function printPostSetupReminder(target, packageManager, { hook, legacyCursorGuard } = {}) {
   const lintTarget = target || 'src';
   const lintCmd = buildLintCommand(packageManager);
   const lines = [
@@ -1001,6 +1061,12 @@ function printPostSetupReminder(target, packageManager, { hook } = {}) {
       );
     }
   }
+  if (legacyCursorGuard) {
+    lines.push(
+      `  ⚠️  ${legacyCursorGuard.path} に旧バージョンの Sparkle Design Guard ブロックが残っています。rc.4 で Cursor のガードは AGENTS.md に統一されました（Cursor の \`.cursor/rules/*.mdc\` は frontmatter で \`alwaysApply: true\` を付けないと条件付き読み込みになり、ガードが silent に skip される問題があるため）。重複防止のため旧 .mdc を削除するか、\`alwaysApply: true\` の frontmatter を付けて意図的に残す運用に切り替えてください。`,
+      `  ⚠️  Found leftover Sparkle Design Guard in ${legacyCursorGuard.path}. rc.4 routes Cursor Guard through AGENTS.md (\`.cursor/rules/*.mdc\` is conditionally loaded unless \`alwaysApply: true\` is set). Either delete the legacy .mdc or add \`alwaysApply: true\` frontmatter to keep it deliberately.`
+    );
+  }
   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-rc.3",
+  "version": "2.0.7-rc.4",
   "description": "Sparkle Design CLI — プロジェクトセットアップ、CSS・フォント生成、アンチパターン検査、AI エージェント（Claude Code / Cursor / Codex）向けのガードと hook 設定まで一括で行う sparkle-design 公式 CLI。",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",