sparkle-design-cli 1.5.1 → 1.6.0

package/bin/sparkle-design.js

@@ -76,6 +76,7 @@ function parseSetupOptions(args) {
   const options = {
     assistant: 'generic',
     target: null,
+    instructionsPath: null,
     dryRun: false,
     forceScriptUpdate: false,
     help: false,
@@ -92,6 +93,9 @@ function parseSetupOptions(args) {
     } else if (arg === '--target') {
       options.target = requireOptionValue(args, i, '--target');
       i += 1;
+    } else if (arg === '--instructions-path') {
+      options.instructionsPath = requireOptionValue(args, i, '--instructions-path');
+      i += 1;
     } else if (arg === '--dry-run') {
       options.dryRun = true;
     } else if (arg === '--force-script-update') {
@@ -138,6 +142,7 @@ Setup:
   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
+  sparkle-design-cli setup --assistant claude --instructions-path app/admin/CLAUDE.md
 
 Generate options:
   -h, --help                 このヘルプメッセージを表示
@@ -179,6 +184,7 @@ Setup options:
   --assistant <name>         claude / codex / cursor / generic (default: generic)
   --target <path>            lint 対象パス (default: auto-detect)
   --dry-run                  ファイルを変更せず結果だけ表示
+  --instructions-path <path> AI 指示ファイルの出力先パス (default: アシスタント別のデフォルト)
   --force-script-update      既存の lint:sparkle 系 script も上書きする
 
 Check で検出する主なパターン:
@@ -195,8 +201,14 @@ Check で検出する主なパターン:
   - disabled を isDisabled の代わりに使っている
   - Button の prefixIcon に JSX を渡している
   - Icon の children にテキストを渡している
+  - globals.css にフォント @import が残っている（SparkleHead への移行が必要）
+  - CSP ヘッダーで Google Fonts がブロックされている可能性
 
 JSON 出力では manualReviewReminders も返すため、AI から実行する場合は --format json を推奨
+
+generate で生成されるファイル:
+  sparkle-design.css         デザイントークン CSS
+  SparkleHead.tsx            フォント読み込み用 React コンポーネント（layout.tsx の <head> に配置）
 `);
 }
 

package/lib/check.js

@@ -2,17 +2,26 @@ import fs from 'fs';
 import path from 'path';
 
 import { getCheckRules, getManualReviewReminders } from './anti-pattern-rules.js';
+import { REGEX, FONT_DOMAINS } from './constants.js';
 
 const DEFAULT_TARGET = 'src';
 const TEXT_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx']);
+const CSS_EXTENSIONS = new Set(['.css']);
 const RULES = getCheckRules();
-const MANUAL_REVIEW_REMINDERS = getManualReviewReminders();
+const BASE_MANUAL_REVIEW_REMINDERS = getManualReviewReminders();
+
+const SPARKLE_HEAD_JSX_PATTERN = /<SparkleHead\s*\/?\s*>/;
+const CSP_PATTERN = /content-security-policy|contentSecurityPolicy|Content-Security-Policy/i;
+const NEXT_CONFIG_CANDIDATES = ['next.config.js', 'next.config.ts', 'next.config.mjs', 'next.config.cjs'];
 
 function toRelativeReportPath(filePath) {
   return path.relative(process.cwd(), filePath).split(path.sep).join('/');
 }
 
-function collectFiles(targetPath, files, visited) {
+/**
+ * ディレクトリを1回だけ走査し、テキストファイルと CSS ファイルを同時に収集する
+ */
+function collectFiles(targetPath, textFiles, cssFiles, visited) {
   if (!fs.existsSync(targetPath)) {
     throw new Error(`Target path does not exist: ${targetPath}`);
   }
@@ -26,8 +35,11 @@ function collectFiles(targetPath, files, visited) {
   const stat = fs.statSync(realPath);
 
   if (stat.isFile()) {
-    if (TEXT_EXTENSIONS.has(path.extname(realPath))) {
-      files.add(realPath);
+    const ext = path.extname(realPath);
+    if (TEXT_EXTENSIONS.has(ext)) {
+      textFiles.add(realPath);
+    } else if (CSS_EXTENSIONS.has(ext)) {
+      cssFiles.add(realPath);
     }
     return;
   }
@@ -41,7 +53,7 @@ function collectFiles(targetPath, files, visited) {
       continue;
     }
 
-    collectFiles(path.join(realPath, entry.name), files, visited);
+    collectFiles(path.join(realPath, entry.name), textFiles, cssFiles, visited);
   }
 }
 
@@ -53,8 +65,7 @@ function formatMatch(match) {
   return match[0].replace(/\s+/g, ' ').trim().slice(0, 120);
 }
 
-function collectFindings(filePath) {
-  const content = fs.readFileSync(filePath, 'utf8');
+function collectFindings(filePath, content) {
   const findings = [];
 
   for (const rule of RULES) {
@@ -73,42 +84,137 @@ function collectFindings(filePath) {
   return findings;
 }
 
+/**
+ * CSS ファイルからフォント @import の残存を検出する
+ */
+function collectFontImportFindings(cssFiles) {
+  const findings = [];
+
+  for (const filePath of cssFiles) {
+    const content = fs.readFileSync(filePath, 'utf8');
+    for (const match of content.matchAll(REGEX.FONT_IMPORT)) {
+      findings.push({
+        filePath,
+        id: 'font-import-in-css',
+        description: 'CSS にフォント @import が残っています。SparkleHead コンポーネントに移行してください。',
+        recommendation: 'sparkle-design-cli generate を再実行すると、フォント読み込みが SparkleHead.tsx に移行され、globals.css から @import が除去されます。',
+        line: getLineNumber(content, match.index ?? 0),
+        snippet: match[0].slice(0, 120),
+      });
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * ソースコード内に <SparkleHead /> の JSX 使用があるか検出する
+ * SparkleHead.tsx 自体の定義は除外し、実際に JSX として使用している箇所のみ検出する
+ */
+function hasSparkleHeadUsage(fileContents) {
+  for (const [filePath, content] of fileContents) {
+    if (path.basename(filePath) === 'SparkleHead.tsx') continue;
+    if (SPARKLE_HEAD_JSX_PATTERN.test(content)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Next.js の CSP ヘッダー設定を検出し、Google Fonts ドメインの許可を確認する
+ */
+function collectNextjsCspFindings(cwd) {
+  const findings = [];
+
+  for (const candidate of NEXT_CONFIG_CANDIDATES) {
+    const configPath = path.resolve(cwd, candidate);
+
+    let content;
+    try {
+      content = fs.readFileSync(configPath, 'utf8');
+    } catch {
+      continue;
+    }
+
+    if (!CSP_PATTERN.test(content)) continue;
+
+    const missingDomains = [
+      { domain: 'fonts.googleapis.com', directive: 'style-src', pattern: new RegExp(FONT_DOMAINS.GOOGLEAPIS.replace('https://', '')) },
+      { domain: 'fonts.gstatic.com', directive: 'font-src', pattern: new RegExp(FONT_DOMAINS.GSTATIC.replace('https://', '')) },
+    ].filter(({ pattern }) => !pattern.test(content));
+
+    if (missingDomains.length > 0) {
+      const missing = missingDomains.map(d => `${d.domain} (${d.directive})`).join(', ');
+      findings.push({
+        filePath: configPath,
+        id: 'csp-font-block',
+        description: `CSP ヘッダーが設定されていますが、${missing} が許可されていない可能性があります。`,
+        recommendation: `style-src に ${FONT_DOMAINS.GOOGLEAPIS} を、font-src に ${FONT_DOMAINS.GSTATIC} を追加してください。`,
+        line: 1,
+        snippet: `Content-Security-Policy detected, missing: ${missing}`,
+      });
+    }
+    break;
+  }
+
+  return findings;
+}
+
 function createCheckReport(targets = []) {
   const resolvedTargets = targets.length > 0 ? targets : [DEFAULT_TARGET];
-  const files = new Set();
+  const textFiles = new Set();
+  const cssFiles = new Set();
   const visited = new Set();
 
+  // 1回のディレクトリ走査でテキストファイルと CSS ファイルを同時に収集
   for (const target of resolvedTargets) {
-    collectFiles(path.resolve(process.cwd(), target), files, visited);
+    collectFiles(path.resolve(process.cwd(), target), textFiles, cssFiles, visited);
   }
 
-  const checkedFiles = [...files]
+  const checkedFiles = [...textFiles]
     .map((filePath) => toRelativeReportPath(filePath))
     .sort((left, right) => left.localeCompare(right));
-  const findings = [...files]
-    .flatMap(collectFindings)
+
+  // ファイル内容を1回だけ読み込んでキャッシュ（collectFindings + hasSparkleHeadUsage で再利用）
+  const fileContents = new Map();
+  for (const filePath of textFiles) {
+    fileContents.set(filePath, fs.readFileSync(filePath, 'utf8'));
+  }
+
+  const findings = [...fileContents.entries()]
+    .flatMap(([filePath, content]) => collectFindings(filePath, content))
     .map((finding) => ({
       ...finding,
       filePath: toRelativeReportPath(finding.filePath),
-    }))
-    .sort((left, right) => {
-      const fileComparison = left.filePath.localeCompare(right.filePath);
-      if (fileComparison !== 0) {
-        return fileComparison;
-      }
-
-      if (left.line !== right.line) {
-        return left.line - right.line;
-      }
-
-      return left.id.localeCompare(right.id);
+    }));
+
+  const fontFindings = collectFontImportFindings(cssFiles);
+  findings.push(...fontFindings.map((f) => ({ ...f, filePath: toRelativeReportPath(f.filePath) })));
+
+  const cspFindings = collectNextjsCspFindings(process.cwd());
+  findings.push(...cspFindings.map((f) => ({ ...f, filePath: toRelativeReportPath(f.filePath) })));
+
+  findings.sort((left, right) => {
+    const fileComparison = left.filePath.localeCompare(right.filePath);
+    if (fileComparison !== 0) return fileComparison;
+    if (left.line !== right.line) return left.line - right.line;
+    return left.id.localeCompare(right.id);
+  });
+
+  const manualReviewReminders = [...BASE_MANUAL_REVIEW_REMINDERS];
+  if (!hasSparkleHeadUsage(fileContents)) {
+    manualReviewReminders.push({
+      id: 'sparkle-head-missing',
+      message: 'SparkleHead がソースコード内に見つかりませんでした。ルートレイアウトの <head> 内に <SparkleHead /> を配置してフォントの早期読み込みを有効にしてください。',
     });
+  }
 
   return {
     targets: resolvedTargets,
     checkedFiles,
     findings,
-    manualReviewReminders: MANUAL_REVIEW_REMINDERS,
+    manualReviewReminders,
   };
 }
 
@@ -171,4 +277,4 @@ export function checkProject(targets = [], options = {}) {
   return report.findings.length > 0;
 }
 
-export { RULES, collectFindings, createCheckReport, MANUAL_REVIEW_REMINDERS };
+export { RULES, collectFindings, createCheckReport, BASE_MANUAL_REVIEW_REMINDERS as MANUAL_REVIEW_REMINDERS };

package/lib/constants.js

@@ -56,6 +56,12 @@ export const PLACEHOLDERS = {
   FONT_FAMILY_MONO: '{{FONT_FAMILY_MONO}}',
 };
 
+// Google Fonts ドメイン
+export const FONT_DOMAINS = {
+  GOOGLEAPIS: 'https://fonts.googleapis.com',
+  GSTATIC: 'https://fonts.gstatic.com',
+};
+
 // フォントのデフォルト設定
 export const FONT_DEFAULTS = {
   WEIGHTS: [400, 700],

package/lib/font-manager.js

@@ -172,19 +172,18 @@ function findTailwindImport(globalsContent) {
 
 /**
  * globals.css を再構築する
+ * フォント @import は SparkleHead.tsx に移行したため、globals.css には差し込まない
  * @param {string} globalsContent 元のglobals.cssの内容
- * @param {string} fontImportBlock フォントimportブロック
  * @param {string} sparkleImportBlock sparkle-design.css importブロック
  * @param {Object} tailwindInfo Tailwind importの情報
  * @returns {string} 再構築されたglobals.css
  */
-function reconstructGlobalsCss(globalsContent, fontImportBlock, sparkleImportBlock, tailwindInfo) {
+function reconstructGlobalsCss(globalsContent, sparkleImportBlock, tailwindInfo) {
   const beforeTailwind = globalsContent.substring(0, tailwindInfo.index);
   const afterTailwind = globalsContent.substring(tailwindInfo.afterIndex);
 
-  // フォントimport + Tailwind + sparkle-design.css + 残りのコンテンツ
+  // Tailwind + sparkle-design.css + 残りのコンテンツ（フォント @import なし）
   return (
-    fontImportBlock +
     beforeTailwind +
     tailwindInfo.match +
     sparkleImportBlock +
@@ -222,14 +221,12 @@ export function updateGlobalsWithFonts(fontImports, globalsPath, sourcePackages
       return false;
     }
 
-    // 4. importブロックを生成
-    const fontImportBlock = createFontImportBlock(fontImports);
+    // 4. importブロックを生成（フォント @import は SparkleHead に移行したため生成しない）
     const sparkleImportBlock = createSparkleImportBlock(sourcePackages, globalsPath, customCssPath);
 
-    // 5. globals.css を再構築
+    // 5. globals.css を再構築（フォント @import なし）
     const reconstructedContent = reconstructGlobalsCss(
       globalsContent,
-      fontImportBlock,
       sparkleImportBlock,
       tailwindInfo
     );

package/lib/generate-css.js

@@ -7,7 +7,7 @@
 
 import fs from 'fs';
 import path from 'path';
-import { REGEX, PATHS, MESSAGES, FONT_DEFAULTS } from './constants.js';
+import { REGEX, PATHS, MESSAGES, FONT_DEFAULTS, FONT_DOMAINS } from './constants.js';
 import {
   loadConfig,
   loadTemplate,
@@ -181,6 +181,80 @@ function generateFontImportsBlock(configOrResolved) {
   return imports.join('\n');
 }
 
+/**
+ * @import 文から Google Fonts の URL を抽出する
+ * @param {string} importLine @import 文
+ * @returns {string} URL
+ */
+function extractUrlFromImport(importLine) {
+  const match = importLine.match(/@import\s+['"]([^'"]+)['"]/);
+  return match ? match[1] : '';
+}
+
+/**
+ * SparkleHead.tsx の内容を生成する
+ * sparkle.config.json のフォント設定に基づき、preconnect + link タグを含む React コンポーネントを生成
+ * @param {Object} resolvedFonts resolveFontConfig の結果
+ * @returns {string} SparkleHead.tsx のファイル内容
+ */
+function generateSparkleHeadContent(resolvedFonts) {
+  const materialSymbolsUrl = extractUrlFromImport(FONT_DEFAULTS.MATERIAL_SYMBOLS_IMPORT);
+  const fontImportLines = generateMergedFontImports([...resolvedFonts.pro, ...resolvedFonts.mono]);
+  const fontUrls = fontImportLines.map(extractUrlFromImport).filter(Boolean);
+
+  const linkTags = [
+    `      <link rel="preconnect" href="${FONT_DOMAINS.GOOGLEAPIS}" />`,
+    `      <link rel="preconnect" href="${FONT_DOMAINS.GSTATIC}" crossOrigin="anonymous" />`,
+    `      <link rel="stylesheet" href="${materialSymbolsUrl}" />`,
+    ...fontUrls.map(url => `      <link rel="stylesheet" href="${url}" />`),
+  ];
+
+  return `/**
+ * Copyright 2026 Goodpatch Inc.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * SparkleHead - フォント読み込みコンポーネント
+ *
+ * sparkle-design-cli generate により sparkle.config.json から自動生成されます。
+ * ルートレイアウトの <head> 内に配置してください。
+ *
+ * @example
+ * import { SparkleHead } from "./SparkleHead";
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html>
+ *       <head>
+ *         <SparkleHead />
+ *       </head>
+ *       <body>{children}</body>
+ *     </html>
+ *   );
+ * }
+ */
+export function SparkleHead() {
+  return (
+    <>
+${linkTags.join('\n')}
+    </>
+  );
+}
+`;
+}
+
+/**
+ * SparkleHead.tsx を書き出す
+ * @param {string} content SparkleHead.tsx の内容
+ * @param {string} sparkleDesignCssPath sparkle-design.css の出力パス（同じディレクトリに配置）
+ */
+function writeSparkleHead(content, sparkleDesignCssPath) {
+  const outputPath = path.join(path.dirname(sparkleDesignCssPath), 'SparkleHead.tsx');
+  fs.writeFileSync(outputPath, content, 'utf8');
+  console.log(`✅ SparkleHead.tsx を生成しました: ${outputPath}`);
+  console.log('   → ルートレイアウトの <head> 内に <SparkleHead /> を追加してください');
+}
+
 /**
  * テンプレート変数を設定値で置換する
  * @param {string} template CSSテンプレート
@@ -250,7 +324,7 @@ function processTemplate(template, config, grayMapping, radiusMapping, colors) {
   processedCSS = dedupeFontImports(processedCSS);
 
   console.log(MESSAGES.TEMPLATE_PROCESSED);
-  return processedCSS;
+  return { css: processedCSS, resolvedFonts };
 }
 
 /**
@@ -304,8 +378,8 @@ export function generateCSS(configPath = null, outputPath = null) {
   const grayMapping = loadGrayMapping();
   const radiusMapping = loadRadiusMapping();
 
-  // 5. テンプレートを設定値で処理
-  const processedCSS = processTemplate(template, config, grayMapping, radiusMapping, colors);
+  // 5. テンプレートを設定値で処理（resolvedFonts も返す）
+  const { css: processedCSS, resolvedFonts } = processTemplate(template, config, grayMapping, radiusMapping, colors);
 
   // 6. CSSファイルを書き出し
   const defaultOutputPath = path.resolve(
@@ -316,7 +390,11 @@ export function generateCSS(configPath = null, outputPath = null) {
   const resolvedOutputPath = outputPath ? path.resolve(outputPath) : defaultOutputPath;
   writeCSS(processedCSS, outputPath);
 
-  // 7. フォント管理の自動処理を実行
+  // 7. SparkleHead.tsx を生成（processTemplate で解決済みの resolvedFonts を再利用）
+  const sparkleHeadContent = generateSparkleHeadContent(resolvedFonts);
+  writeSparkleHead(sparkleHeadContent, resolvedOutputPath);
+
+  // 8. フォント管理の自動処理を実行（globals.css にはフォント @import を差し込まない）
   console.log(MESSAGES.FONT_MANAGEMENT_START);
   const sourcePackages = 'source-packages' in config ? (config['source-packages'] || []) : null;
   const customCssPath = config['custom-css'] || null;

package/lib/setup.js

@@ -43,36 +43,49 @@ function writeJson(filePath, value) {
   fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
 }
 
-function normalizeTarget(cwd, target, sourceLabel) {
-  const trimmed = target.trim();
+/**
+ * 相対パスのバリデーションと正規化
+ * @param {string} cwd プロジェクトルート
+ * @param {string} inputPath 入力パス
+ * @param {string} label エラーメッセージ用ラベル
+ * @param {{ checkParentOnly?: boolean }} options
+ *   checkParentOnly: true の場合、パス自体ではなく親ディレクトリの存在をチェック（新規ファイル作成用）
+ */
+function normalizePath(cwd, inputPath, label, { checkParentOnly = false } = {}) {
+  const trimmed = inputPath.trim();
 
   if (!trimmed) {
-    throw new Error(`Target path is empty (${sourceLabel})`);
+    throw new Error(`${label} is empty`);
   }
 
   if (path.isAbsolute(trimmed)) {
-    throw new Error(`Target path must be relative to the project root: ${trimmed}`);
+    throw new Error(`${label} must be relative to the project root: ${trimmed}`);
   }
 
   if (UNSAFE_TARGET_PATTERN.test(trimmed)) {
     throw new Error(
-      `Target path contains unsupported characters: ${trimmed}. Use a simple relative path without spaces or shell metacharacters.`
+      `${label} contains unsupported characters: ${trimmed}. Use a simple relative path.`
     );
   }
 
   const normalized = path.posix.normalize(trimmed.replace(/\\/g, '/'));
 
-  if (normalized === '.' || normalized === '') {
-    throw new Error(`Target path is empty (${sourceLabel})`);
+  if (!checkParentOnly && (normalized === '.' || normalized === '')) {
+    throw new Error(`${label} is empty`);
   }
 
   if (normalized.startsWith('../')) {
-    throw new Error(`Target path must stay inside the project root: ${trimmed}`);
+    throw new Error(`${label} must stay inside the project root: ${trimmed}`);
   }
 
-  const absolutePath = path.resolve(cwd, normalized);
-  if (!fs.existsSync(absolutePath)) {
-    throw new Error(`Target path does not exist: ${normalized}`);
+  const checkPath = checkParentOnly
+    ? path.resolve(cwd, path.dirname(normalized))
+    : path.resolve(cwd, normalized);
+
+  if (!fs.existsSync(checkPath)) {
+    const desc = checkParentOnly ? 'Parent directory' : 'Path';
+    const displayPath = checkParentOnly ? path.dirname(normalized) : normalized;
+    throw new Error(`${desc} does not exist: ${displayPath}`);
   }
 
   return normalized;
@@ -221,15 +234,17 @@ export function setupAssistant(options = {}) {
 
   const targetSource = options.target ? 'explicit' : 'auto';
   const target = options.target
-    ? normalizeTarget(cwd, options.target, 'explicit')
-    : normalizeTarget(cwd, detectTarget(cwd), 'auto');
+    ? normalizePath(cwd, options.target, 'Target path')
+    : normalizePath(cwd, detectTarget(cwd), 'Target path');
 
   const packageJsonPath = path.resolve(cwd, 'package.json');
   if (!fs.existsSync(packageJsonPath)) {
     throw new Error(`package.json not found in ${cwd}`);
   }
 
-  const instructionPath = path.resolve(cwd, assistantConfig.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 instructionResult = updateInstructionFile(instructionPath, instructionBlock);

package/package.json

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