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

package/README.md

@@ -15,7 +15,7 @@ setup は次を自動で行います:
 1. パッケージマネージャー（pnpm / npm / yarn / bun）を自動検出
 2. `sparkle-design` を dependencies、`tailwindcss` + `@tailwindcss/postcss` を devDependencies に追加
 3. 未作成の場合のみ初期ファイルを生成:
-   - `sparkle.config.json`（デフォルトは blue / Inter / JetBrains Mono / md）
+   - `sparkle.config.json`（デフォルトは blue / BIZ UDPGothic / BIZ UDGothic / md — sparkle-design 本体のデフォルトに合わせて統一）
    - `postcss.config.mjs`
    - Tailwind エントリ CSS — Next.js App Router なら `src/app/globals.css`、Vite なら `src/index.css`、それ以外は `src/globals.css`（プロジェクト構成から自動判定）
 4. AI 指示ファイル（`CLAUDE.md` / `AGENTS.md` / Cursor rules）に Sparkle Design Guard ブロックを追加
@@ -35,10 +35,10 @@ npm install -g sparkle-design-cli
 
 npm の dist-tag でチャネルを分離しています。通常は latest を使い、品質保証中の変更を試したい場合のみ beta を指定してください。
 
-| チャネル | dist-tag | 用途 | 指定方法 |
-|---------|---------|------|---------|
-| 安定版 | `latest` | 本番運用向け。`npx --yes sparkle-design-cli` は常にこれを取得 | （デフォルト） |
-| Beta | `beta` | 品質保証中の検証用 | `npx --yes sparkle-design-cli@beta` |
+| チャネル | dist-tag | 用途                                                          | 指定方法                            |
+| -------- | -------- | ------------------------------------------------------------- | ----------------------------------- |
+| 安定版   | `latest` | 本番運用向け。`npx --yes sparkle-design-cli` は常にこれを取得 | （デフォルト）                      |
+| Beta     | `beta`   | 品質保証中の検証用                                            | `npx --yes sparkle-design-cli@beta` |
 
 ```bash
 # beta で setup を試す
@@ -103,6 +103,12 @@ sparkle-design-cli generate --output ./styles/design.css
 
 # 設定ファイルと出力先を両方指定
 sparkle-design-cli generate -c ./config/custom.json -o ./dist/styles.css
+
+# Tailwind エントリ CSS を明示指定
+sparkle-design-cli generate --globals-path src/styles/app.css
+
+# CI 向け: @source 注入や Tailwind import 欠落などの失敗を exit 1 にする
+sparkle-design-cli generate --strict
 ```
 
 #### generate オプション一覧
@@ -110,6 +116,12 @@ sparkle-design-cli generate -c ./config/custom.json -o ./dist/styles.css
 - `-h, --help`: ヘルプメッセージを表示
 - `-c, --config <パス>`: 設定ファイルのパス（デフォルト: `./sparkle.config.json`）
 - `-o, --output <パス>`: 出力ファイルのパス（デフォルト: `./src/app/sparkle-design.css`）
+- `--globals-path <パス>`: Tailwind エントリポイント CSS のパス（デフォルト: 自動検出）。
+  **指定したパスが存在しない場合は `--strict` の有無に関わらず常に exit 1**（`sparkle.config.json` の `extend.globals-path` も同様）
+- `--strict`: 以下を warn ではなく **exit 1** に昇格させる（CI 向け。既定は warn + 継続で後方互換を維持）:
+  - デザインシステムパッケージが `package.json` に入っているのに Tailwind エントリ CSS が見つからない
+  - エントリ CSS はあるが `@import "tailwindcss";` が書かれていない（警告メッセージに追記すべき行まで actionable に表示）
+  - エントリ CSS への書き込みに失敗した
 
 ### check: アンチパターン検査
 
@@ -142,24 +154,15 @@ sparkle-design-cli check --help
 - children なしの Button に prefixIcon / suffixIcon を使わない
 - Material Symbols を className 直書きで使わない
 - shadcn/ui 既定 token を Sparkle Design 内へ持ち込まない
-- Tailwind デフォルト typography（text-sm, font-medium 等）を使わない
-- CardTitle に typography を上書きしない
+- Tailwind デフォルト typography を Sparkle Design コンポーネント内で使わない
+- CardTitle に typography 系クラスを付与しない
 - CardControl に Button / IconButton 以外を入れない
-- CardHeader / CardContent の padding を上書きしない
-- asChild と prefixIcon / suffixIcon / isLoading を併用しない
-- disabled を isDisabled の代わりに使わない
-- Button の prefixIcon に JSX を渡さない
+- Card 系コンポーネントのデフォルト padding を安易に上書きしない
+- asChild 使用時に prefixIcon / suffixIcon / isLoading を使わない
+- Sparkle Design コンポーネントでは isDisabled を使う
+- Button の prefixIcon / suffixIcon に JSX を渡さない
 - Icon の children にテキストを渡さない
-- クリック可能な Card を `<button>` / `<a>` / `role="button"` でラップせず、`ClickableCard` を使う
-
-#### Manual Review Reminders
-
-`--format json` では、機械検出できない観点も `manualReviewReminders` として返します。現在は次を含みます。
-
-- Badge と Tag の意味的な使い分け
-- CardDescription の typography / color token 明示
-- Dialog と Modal の UX 上の使い分け
-- 手書き span が Tag で置き換え可能か
+- クリック可能な Card は ClickableCard を使う（button / a / role="button" でラップしない）
 
 #### 導入先での推奨設定
 
@@ -198,6 +201,7 @@ npx --yes sparkle-design-cli setup --assistant claude --skip-install --skip-scaf
 ```
 
 既存ファイルは上書きされません:
+
 - `sparkle.config.json` / `postcss.config.*` / Tailwind エントリ CSS が存在する場合はそのまま保持
 - 既に依存関係に入っているパッケージはインストールをスキップ
 - `package.json` の既存の `lint:sparkle*` 独自 script は保持（`--force-script-update` で上書き）
@@ -205,6 +209,7 @@ npx --yes sparkle-design-cli setup --assistant claude --skip-install --skip-scaf
 `--target` を省略した場合、lint 対象は `src`, `src/components`, `src/features`, `app`, `components` の順で自動検出されます。
 
 利用できる assistant:
+
 - `claude`: `CLAUDE.md`
 - `codex`: `AGENTS.md`
 - `cursor`: `.cursor/rules/sparkle-design-guard.mdc`
@@ -220,6 +225,9 @@ npx --yes sparkle-design-cli setup --assistant claude --skip-install --skip-scaf
 - `--skip-generate`: `generate` 実行をスキップ
 - `--dry-run`: ファイルを変更せず結果だけ表示
 - `--force-script-update`: 既存の `lint:sparkle` 系 script も上書き
+- `--strict`: `generate` ステージの失敗を exit 1 に昇格（CI 向け）。
+  現状は `generate` の失敗のみ対象（install / scaffold / guard の失敗は従来どおり warn）。
+  `--skip-generate` / `--dry-run` と併用した場合は strict チェック対象が無くなるため警告を出します。
 
 `setup` は通常実行時も JSON サマリーを stdout に表示します。`--dry-run` を付けると、その JSON を表示したままファイル変更だけを抑止します。
 
@@ -259,9 +267,7 @@ Figma プラグインが出力する基本4項目に加えて、プロジェク
         { "family": "Montserrat", "weights": [500, 600, 700] },
         { "family": "Noto Sans JP", "weights": [400, 500, 600, 700] }
       ],
-      "mono": [
-        { "family": "Roboto Mono", "weights": [400, 700] }
-      ]
+      "mono": [{ "family": "Roboto Mono", "weights": [400, 700] }]
     },
     "source-packages": ["@goodpatch/sparkle-design-internal"],
     "custom-css": "./src/app/custom-tokens.css"

package/bin/sparkle-design.js

@@ -19,6 +19,7 @@ function parseGenerateOptions(args) {
     configPath: null,
     outputPath: null,
     globalsPath: null,
+    strict: false,
     help: false,
   };
 
@@ -36,6 +37,8 @@ function parseGenerateOptions(args) {
     } else if (arg === '--globals-path') {
       options.globalsPath = requireOptionValue(args, i, '--globals-path');
       i += 1;
+    } else if (arg === '--strict') {
+      options.strict = true;
     } else {
       throw new Error(`Unknown option for generate: ${arg}`);
     }
@@ -86,6 +89,7 @@ function parseSetupOptions(args) {
     skipInstall: false,
     skipScaffold: false,
     skipGenerate: false,
+    strict: false,
     help: false,
   };
 
@@ -113,6 +117,8 @@ function parseSetupOptions(args) {
       options.skipScaffold = true;
     } else if (arg === '--skip-generate') {
       options.skipGenerate = true;
+    } else if (arg === '--strict') {
+      options.strict = true;
     } else {
       throw new Error(`Unknown option for setup: ${arg}`);
     }
@@ -161,6 +167,8 @@ Generate options:
   -c, --config <path>        設定ファイルのパス (default: ./sparkle.config.json)
   -o, --output <path>        出力ファイルのパス (default: ./src/app/sparkle-design.css)
   --globals-path <path>      Tailwind エントリポイント CSS のパス (default: 自動検出)
+  --strict                   globals.css への @source 注入等が失敗したら exit 1
+                             (CI 向け。既定は warn + 継続で後方互換を維持)
 
 sparkle.config.json の設定フィールド:
 
@@ -204,6 +212,7 @@ Setup options:
   --skip-install             パッケージインストール（sparkle-design, tailwindcss）をスキップ
   --skip-scaffold            初期ファイル（sparkle.config.json, postcss.config, エントリ CSS）生成をスキップ
   --skip-generate            generate 実行をスキップ
+  --strict                   generate の失敗を exit 1 に昇格（CI 向け）
 
 Setup の動作:
   1. パッケージマネージャー検出（pnpm / npm / yarn / bun）
@@ -257,7 +266,9 @@ function main() {
         process.exit(0);
       }
 
-      generateCSS(options.configPath, options.outputPath, options.globalsPath);
+      generateCSS(options.configPath, options.outputPath, options.globalsPath, {
+        strict: options.strict,
+      });
       return;
     }
 

package/lib/anti-pattern-rules.js

@@ -971,21 +971,35 @@ const ANTI_PATTERN_GROUPS = [
       description: 'CardControl に Button / IconButton 以外を入れない',
       recommendation:
         'CardControl はアクションボタン用です。ステータス表示には CardDescription を使ってください。',
-      // 以前の regex は `[\s\S]*?` が `</CardControl>` を越えて貪欲に探索してしまい、
-      // 隣接する <CardContent> 等を非 Button 子要素として誤検知していた。
-      // 内部コンテンツが `</CardControl>` を越えないよう lazy 側に停止条件を入れ、
-      // 開始タグの直後から終了タグ直前までの範囲だけを検査する。
-      // 加えて (1) 開始タグ自体が自己閉じ `/>` で終わっていたら子要素は存在しない
-      // ので検査対象外とする（`[^>/]*[^>/]?`）、(2) ネストした `<CardControl>` も
-      // Button/IconButton 扱いのスキップリストに加えて誤発報を防ぐ。
-      // en: The previous pattern let `[\s\S]*?` leak past `</CardControl>`,
-      // flagging adjacent siblings (e.g. `<CardContent>`) as non-Button children.
-      // We now (a) constrain the lazy body so it cannot cross the closing tag,
-      // (b) skip self-closing tags `<CardControl />` entirely, and
-      // (c) treat a nested `<CardControl>` as an allowed child so we don't
-      // report the inner wrapper of a pathological nested structure.
-      pattern:
-        /<CardControl\b(?:[^>]*[^>/])?>(?:(?!<\/CardControl\b)[\s\S])*?<(?!Button\b|IconButton\b|CardControl\b|\/CardControl\b)[A-Za-z][\w.]*/g,
+      // 2-pass matcher。1 本の regex に入れ子 negative lookahead を押し込む代わりに、
+      // まず <CardControl>…</CardControl> ブロックを抽出し、次にブロック内部だけを
+      // スキャンして Button / IconButton / 入れ子 CardControl 以外の開始タグを見つける。
+      //   1. 入れ子 negative lookahead が無くなり読みやすい
+      //   2. 自己閉じ `<CardControl />` は 1st pass でそもそも拾わない（special case 不要）
+      //   3. O(総コンテンツ長) で評価が済むため、大規模 JSX でも backtracking で
+      //      処理時間が跳ねない
+      // en: Two-pass matcher. First pass extracts `<CardControl>…</CardControl>`
+      // blocks (self-closing variants are skipped because the opening-tag regex
+      // requires the previous char not to be `/`). Second pass scans the inner
+      // content for any element that is not Button / IconButton / nested
+      // CardControl. This replaces the nested tempered-lazy regex with a shape
+      // that is easier to reason about and stays linear in total content length.
+      match: (content) => {
+        const BLOCK_PATTERN = /<CardControl\b[^>]*(?<!\/)>([\s\S]*?)<\/CardControl\b[^>]*>/g;
+        const NON_BUTTON_CHILD = /<(?!Button\b|IconButton\b|CardControl\b)[A-Za-z][\w.]*/g;
+        const results = [];
+        for (const blockMatch of content.matchAll(BLOCK_PATTERN)) {
+          const openingEnd = blockMatch.index + blockMatch[0].indexOf('>') + 1;
+          const inner = blockMatch[1];
+          for (const childMatch of inner.matchAll(NON_BUTTON_CHILD)) {
+            results.push({
+              index: openingEnd + childMatch.index,
+              text: childMatch[0],
+            });
+          }
+        }
+        return results;
+      },
     },
     featureSection: lines([
       '### CardControl にはアクションボタンのみを入れる',

package/lib/check.js

@@ -12,7 +12,12 @@ 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'];
+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('/');
@@ -65,10 +70,30 @@ function formatMatch(match) {
   return match[0].replace(/\s+/g, ' ').trim().slice(0, 120);
 }
 
+function formatSnippet(text) {
+  return text.replace(/\s+/g, ' ').trim().slice(0, 120);
+}
+
 function collectFindings(filePath, content) {
   const findings = [];
 
   for (const rule of RULES) {
+    if (typeof rule.match === 'function') {
+      // rule.match(content) -> Array<{ index: number, text: string }>
+      // 複雑な照合が必要なルール向けの opt-in API。2-pass 方式などで regex 単体の
+      // backtracking リスクを回避したいときに使う。index は content 内の絶対オフセット。
+      for (const hit of rule.match(content)) {
+        findings.push({
+          filePath,
+          id: rule.id,
+          description: rule.description,
+          recommendation: rule.recommendation,
+          line: getLineNumber(content, hit.index ?? 0),
+          snippet: formatSnippet(hit.text ?? ''),
+        });
+      }
+      continue;
+    }
     for (const match of content.matchAll(rule.pattern)) {
       findings.push({
         filePath,
@@ -96,8 +121,10 @@ function collectFontImportFindings(cssFiles) {
       findings.push({
         filePath,
         id: 'font-import-in-css',
-        description: 'CSS にフォント @import が残っています。SparkleHead コンポーネントに移行してください。',
-        recommendation: 'sparkle-design-cli generate を再実行すると、フォント読み込みが SparkleHead.tsx に移行され、globals.css から @import が除去されます。',
+        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),
       });
@@ -140,12 +167,20 @@ function collectNextjsCspFindings(cwd) {
     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://', '')) },
+      {
+        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(', ');
+      const missing = missingDomains.map((d) => `${d.domain} (${d.directive})`).join(', ');
       findings.push({
         filePath: configPath,
         id: 'csp-font-block',
@@ -206,7 +241,8 @@ function createCheckReport(targets = []) {
   if (!hasSparkleHeadUsage(fileContents)) {
     manualReviewReminders.push({
       id: 'sparkle-head-missing',
-      message: 'SparkleHead がソースコード内に見つかりませんでした。ルートレイアウトの <head> 内に <SparkleHead /> を配置してフォントの早期読み込みを有効にしてください。',
+      message:
+        'SparkleHead がソースコード内に見つかりませんでした。ルートレイアウトの <head> 内に <SparkleHead /> を配置してフォントの早期読み込みを有効にしてください。',
     });
   }
 
@@ -277,4 +313,9 @@ export function checkProject(targets = [], options = {}) {
   return report.findings.length > 0;
 }
 
-export { RULES, collectFindings, createCheckReport, BASE_MANUAL_REVIEW_REMINDERS as MANUAL_REVIEW_REMINDERS };
+export {
+  RULES,
+  collectFindings,
+  createCheckReport,
+  BASE_MANUAL_REVIEW_REMINDERS as MANUAL_REVIEW_REMINDERS,
+};

package/lib/constants.js

@@ -170,7 +170,11 @@ export const MESSAGES = {
   FONT_REMOVE_SKIPPED: 'ℹ️  globals.css の更新に失敗したため、フォントimport削除をスキップします。',
 
   // 警告メッセージ
-  TAILWIND_NOT_FOUND: '⚠️  globals.css に Tailwind import が見つかりません。',
+  // 指定された globals.css に Tailwind import が無いと @source / sparkle-design.css
+  // の挿入ができないため、どのファイルに何を書けばよいかを示す actionable なメッセージにする。
+  // en: Make the warning actionable — tell the user which file to edit and what to add.
+  TAILWIND_NOT_FOUND: (path) =>
+    `⚠️  ${path} に Tailwind import が見つかりません。ファイル先頭に \`@import "tailwindcss";\` を追記してください。`,
   GLOBALS_UPDATE_FAILED: (error) => `⚠️  globals.css の更新に失敗しました: ${error}`,
   FONT_MANAGEMENT_ERROR: (error) => `⚠️  フォント管理処理でエラーが発生しました: ${error}`,
   COLOR_CONVERSION_FAILED: (hex) => `⚠️ 色の変換に失敗しました: ${hex}`,

package/lib/font-manager.js

@@ -190,18 +190,20 @@ function reconstructGlobalsCss(globalsContent, sparkleImportBlock, tailwindInfo)
  * - sparkle-design.css importをTailwindの後に配置
  * - 自動検出した sourcePackages から @source ディレクティブを挿入
  *
- * **v2.0.7-beta.1 以前の不具合**: 早期 return が `fontImports.length === 0` 単独で
- * 行われていたため、フォントを SparkleHead に移行済みかつ既存 globals.css が
- * ある（Vite の `src/index.css` など）プロジェクトでは `@source` が一切挿入
- * されなかった。条件を「フォント・sourcePackages・customCssPath のすべてが
- * 空なら skip」に変更し、パッケージの自動検出結果だけでも globals.css が
- * patch されるようにした。
+ * **v2.0.7-beta.2**: 戻り値を真偽値から `{ status, reason }` の状態付きに変更。
+ * 呼び出し側が「作業不要でスキップ」「失敗したがデフォルトは warn 継続」を
+ * 区別できるようにし、`--strict` モードで失敗を exit code に反映できるよう
+ * にした（#31）。`skipped` は後方互換のため `false` に、`updated` は `true`
+ * に toBoolean で扱える想定。
  *
  * @param {Array<string>} fontImports フォントimport文の配列
  * @param {string} globalsPath globals.cssのパス
  * @param {Array<string>|null} sourcePackages 追加パッケージ名の配列（null の場合は @source を生成しない）
  * @param {string|null} customCssPath custom-css ファイルの相対パス
- * @returns {boolean} globals.css の更新に成功した場合は true
+ * @returns {{ status: 'skipped' | 'updated' | 'failed', reason?: string }}
+ *   skipped: 触る理由がない (fonts/sourcePackages/customCss すべて空)
+ *   updated: globals.css を正常に書き換えた
+ *   failed: 書き換え対象だったが失敗した (TAILWIND_IMPORT 欠落、write 失敗等)
  */
 export function updateGlobalsWithFonts(
   fontImports,
@@ -217,7 +219,7 @@ export function updateGlobalsWithFonts(
   // 理由がないので skip。
   // en: Nothing to inject, so leave globals.css alone.
   if (!hasFonts && !hasSourcePackages && !hasCustomCss) {
-    return false;
+    return { status: 'skipped', reason: 'no-work' };
   }
 
   try {
@@ -230,8 +232,12 @@ export function updateGlobalsWithFonts(
     // 3. Tailwind import の位置を見つける
     const tailwindInfo = findTailwindImport(globalsContent);
     if (!tailwindInfo) {
-      console.warn(MESSAGES.TAILWIND_NOT_FOUND);
-      return false;
+      // 表示はプロジェクト相対パスにする。絶対パスだと「どのファイルをいじるのか」
+      // が一目で分かりにくく、リポジトリ間で絶対パスが変わるので diff も読みにくい。
+      // en: Show the project-relative path so it's obvious which file to edit.
+      const displayPath = path.relative(process.cwd(), globalsPath) || globalsPath;
+      console.warn(MESSAGES.TAILWIND_NOT_FOUND(displayPath));
+      return { status: 'failed', reason: 'tailwind-import-missing' };
     }
 
     // 4. importブロックを生成（フォント @import は SparkleHead に移行したため生成しない）
@@ -247,11 +253,10 @@ export function updateGlobalsWithFonts(
     // 6. 更新したglobals.cssを書き込む
     fs.writeFileSync(globalsPath, reconstructedContent, 'utf8');
     console.log(MESSAGES.GLOBALS_UPDATED(globalsPath));
-    return true;
+    return { status: 'updated' };
   } catch (error) {
     console.error(MESSAGES.GLOBALS_UPDATE_FAILED(error.message));
-    // globals.cssの更新は必須ではないので、エラーでも処理を続行
-    return false;
+    return { status: 'failed', reason: `write-error: ${error.code ?? error.message}` };
   }
 }
 
@@ -355,8 +360,17 @@ function resolveGlobalsPath(sparkleDesignPath, explicitGlobalsPath = null) {
     if (fs.existsSync(resolved)) {
       return { path: resolved, source: 'explicit' };
     }
-    console.warn(`⚠️  指定された globals パスが見つかりません: ${explicitGlobalsPath}`);
-    return null;
+    // 明示指定は settings bug / typo なので silent warn ではなく throw に
+    // 昇格させる。--strict の有無に関わらず呼び出し元で伝播させたいので、
+    // error.code を付けて上流で識別できるようにする。
+    // en: An explicit --globals-path value that doesn't exist is almost
+    // always a typo. We tag the error so manageFontImports's catch knows
+    // to re-throw regardless of strict mode.
+    const err = new Error(
+      `指定された globals パスが見つかりません: ${explicitGlobalsPath} (cwd 基準で解決: ${resolved})`
+    );
+    err.code = 'E_EXPLICIT_GLOBALS_PATH_NOT_FOUND';
+    throw err;
   }
 
   // 1. 自動検出: sparkle-design.css と同じディレクトリで @import "tailwindcss" を含む
@@ -420,24 +434,54 @@ function resolveGlobalsPath(sparkleDesignPath, explicitGlobalsPath = null) {
 /**
  * フォント管理の自動処理を実行する
  * sparkle-design.css からフォントimportを抽出し、Tailwind エントリポイント CSS に @source 等を挿入する
+ *
+ * **v2.0.7-beta.2**: 戻り値を `{ status, reason? }` に変更し、呼び出し側が
+ * 「作業不要のスキップ」「作業すべき状態だが失敗」を区別できるようにした
+ * (#31)。`options.strict` が true のとき、`status === 'failed'` になる状態は
+ * throw に昇格させて `bin/sparkle-design.js` の outer catch で exit 1 に
+ * 繋げる。
+ *
  * @param {string} sparkleDesignPath sparkle-design.cssのパス
  * @param {Array<string>|null} sourcePackages 追加パッケージ名の配列（null の場合は @source を生成しない）
  * @param {string|null} customCssPath custom-css ファイルの相対パス
  * @param {string|null} globalsPathOverride 明示的に指定された globals パス
+ * @param {{ strict?: boolean }} [options] strict=true のとき失敗を throw する
+ * @returns {{ status: 'skipped' | 'updated' | 'failed', reason?: string }}
  */
 export function manageFontImports(
   sparkleDesignPath,
   sourcePackages = null,
   customCssPath = null,
-  globalsPathOverride = null
+  globalsPathOverride = null,
+  options = {}
 ) {
+  const strict = Boolean(options.strict);
+  const hasWork =
+    (sourcePackages !== null && sourcePackages !== undefined) || Boolean(customCssPath);
+
+  const raiseOrReturn = (result) => {
+    if (strict && result.status === 'failed') {
+      throw new Error(
+        `globals.css の更新に失敗しました (${result.reason ?? 'unknown'})。--strict モードでは exit 1 で終了します。`
+      );
+    }
+    return result;
+  };
+
   try {
     // 1. globals パスを解決
     const resolved = resolveGlobalsPath(sparkleDesignPath, globalsPathOverride);
 
     if (!resolved) {
+      // 作業すべき状態（sourcePackages 等あり）で entry CSS が見つからないのは
+      // 事実上の不具合。strict なら throw、非 strict なら従来どおり情報ログ。
+      // en: With work queued, missing entry CSS is effectively a misconfiguration.
+      if (hasWork) {
+        console.warn(MESSAGES.GLOBALS_NOT_FOUND);
+        return raiseOrReturn({ status: 'failed', reason: 'entry-css-not-found' });
+      }
       console.log(MESSAGES.GLOBALS_NOT_FOUND);
-      return;
+      return { status: 'skipped', reason: 'entry-css-not-found-no-work' };
     }
 
     const globalsPath = resolved.path;
@@ -460,17 +504,13 @@ export function manageFontImports(
     }
 
     // 4. globals.css に import / @source を追加
-    const globalsUpdated = updateGlobalsWithFonts(
-      fontImports,
-      globalsPath,
-      sourcePackages,
-      customCssPath
-    );
+    const result = updateGlobalsWithFonts(fontImports, globalsPath, sourcePackages, customCssPath);
 
-    if (!globalsUpdated) {
-      // fonts が元々無く sourcePackages / customCss も空なら更新不要。
-      // en: Nothing to do — not an error.
-      return;
+    if (result.status === 'skipped') {
+      return result;
+    }
+    if (result.status === 'failed') {
+      return raiseOrReturn(result);
     }
 
     // 5. fonts が sparkle-design.css 側に残っていれば削除（globals 側に移動済みの前提）
@@ -480,8 +520,15 @@ export function manageFontImports(
       fs.writeFileSync(sparkleDesignPath, cleanedSparkleContent, 'utf8');
       console.log(MESSAGES.FONT_REMOVED);
     }
+    return result;
   } catch (error) {
     console.error(MESSAGES.FONT_MANAGEMENT_ERROR(error.message));
-    // フォント管理は必須ではないので、エラーでも処理を続行
+    // strict モード、または明示指定された globals path の not-found は
+    // ユーザーが必ず気付くべきなので非 strict でも再 throw する。
+    // en: Always re-throw explicit --globals-path typos; respect strict for the rest.
+    if (strict || error.code === 'E_EXPLICIT_GLOBALS_PATH_NOT_FOUND') {
+      throw error;
+    }
+    return { status: 'failed', reason: `manage-error: ${error.code ?? error.message}` };
   }
 }

package/lib/generate-css.js

@@ -68,7 +68,7 @@ function dedupeFontImports(cssContent) {
 
   return cssContent
     .split('\n')
-    .filter(line => {
+    .filter((line) => {
       if (!line.includes('fonts.googleapis.com')) {
         return true;
       }
@@ -96,7 +96,7 @@ function normalizeFontsEntry(entry) {
     return [{ family: entry, weights: FONT_DEFAULTS.WEIGHTS }];
   }
   if (Array.isArray(entry)) {
-    return entry.map(item => {
+    return entry.map((item) => {
       if (typeof item === 'string') {
         return { family: item, weights: FONT_DEFAULTS.WEIGHTS };
       }
@@ -132,7 +132,7 @@ function resolveFontConfig(config) {
  * @returns {string} CSS font-family 値（例: 'Montserrat', 'Noto Sans JP', sans-serif）
  */
 function generateFontFamilyValue(fonts, genericFamily) {
-  const quoted = fonts.map(f => `'${f.family}'`);
+  const quoted = fonts.map((f) => `'${f.family}'`);
   return [...quoted, genericFamily].join(', ');
 }
 
@@ -169,9 +169,10 @@ function generateMergedFontImports(allFonts) {
  * @returns {string} フォント import ブロック
  */
 function generateFontImportsBlock(configOrResolved) {
-  const { pro, mono } = configOrResolved.pro && configOrResolved.mono
-    ? configOrResolved
-    : resolveFontConfig(configOrResolved);
+  const { pro, mono } =
+    configOrResolved.pro && configOrResolved.mono
+      ? configOrResolved
+      : resolveFontConfig(configOrResolved);
 
   const imports = [
     FONT_DEFAULTS.MATERIAL_SYMBOLS_IMPORT,
@@ -206,7 +207,7 @@ function generateSparkleHeadContent(resolvedFonts) {
     `      <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}" />`),
+    ...fontUrls.map((url) => `      <link rel="stylesheet" href="${url}" />`),
   ];
 
   return `/**
@@ -289,7 +290,15 @@ function processTemplate(template, config, grayMapping, radiusMapping, colors) {
   // 5. 基本的な設定値による置換（オブジェクト・配列・拡張フィールドはスキップ）
   Object.entries(config).forEach(([key, value]) => {
     // 配列・オブジェクト・拡張フィールドはスキップ
-    if (Array.isArray(value) || (typeof value === 'object' && value !== null) || key === 'custom-css' || key === 'fonts' || key === 'extend' || key === 'source-packages' || key === 'globals-path') {
+    if (
+      Array.isArray(value) ||
+      (typeof value === 'object' && value !== null) ||
+      key === 'custom-css' ||
+      key === 'fonts' ||
+      key === 'extend' ||
+      key === 'source-packages' ||
+      key === 'globals-path'
+    ) {
       return;
     }
     // 通常のプレースホルダー（CSS用 - スペースはそのまま）
@@ -336,9 +345,7 @@ function processTemplate(template, config, grayMapping, radiusMapping, colors) {
 // `sparkle-design` は CLI 側のデフォルトパッケージなのでリストには加えず「存在判定」にだけ使う。
 // en: Known design-system packages to auto-detect. `sparkle-design` is the CLI's
 //     default source package, so it only acts as an "enables @source" signal.
-const KNOWN_DESIGN_SYSTEM_PACKAGES = [
-  '@goodpatch/sparkle-design-internal',
-];
+const KNOWN_DESIGN_SYSTEM_PACKAGES = ['@goodpatch/sparkle-design-internal'];
 
 /**
  * package.json の dependencies / devDependencies から既知のデザインシステムパッケージを検出する。
@@ -394,8 +401,17 @@ function writeCSS(cssContent, outputPath = null) {
  * メイン処理
  * @param {string|null} configPath カスタム設定ファイルのパス（オプション）
  * @param {string|null} outputPath カスタム出力パス（オプション）
+ * @param {string|null} globalsPath 明示指定の globals.css パス（オプション）
+ * @param {{ strict?: boolean }} [options] strict=true のとき、
+ *   globals.css パッチ失敗などを throw に昇格させる（exit 1 に繋げるため）
+ * @returns {{ globalsResult: { status: 'skipped'|'updated'|'failed', reason?: string } }}
  */
-export function generateCSS(configPath = null, outputPath = null, globalsPath = null) {
+export function generateCSS(
+  configPath = null,
+  outputPath = null,
+  globalsPath = null,
+  options = {}
+) {
   console.log(MESSAGES.START);
 
   // 1. 設定ファイルを読み込み
@@ -413,7 +429,13 @@ export function generateCSS(configPath = null, outputPath = null, globalsPath =
   const radiusMapping = loadRadiusMapping();
 
   // 5. テンプレートを設定値で処理（resolvedFonts も返す）
-  const { css: processedCSS, resolvedFonts } = processTemplate(template, config, grayMapping, radiusMapping, colors);
+  const { css: processedCSS, resolvedFonts } = processTemplate(
+    template,
+    config,
+    grayMapping,
+    radiusMapping,
+    colors
+  );
 
   // 6. CSSファイルを書き出し
   const defaultOutputPath = path.resolve(
@@ -437,16 +459,23 @@ export function generateCSS(configPath = null, outputPath = null, globalsPath =
   //     with explicit config entries. If neither surfaces anything, @source is skipped.
   console.log(MESSAGES.FONT_MANAGEMENT_START);
   const detectedPackages = detectSourcePackagesFromPackageJson();
-  const explicitPackages = 'source-packages' in config ? (config['source-packages'] || []) : null;
+  const explicitPackages = 'source-packages' in config ? config['source-packages'] || [] : null;
   const sourcePackages =
     detectedPackages !== null || explicitPackages !== null
       ? [...new Set([...(detectedPackages ?? []), ...(explicitPackages ?? [])])]
       : null;
   const customCssPath = config['custom-css'] || null;
   const globalsPathOverride = globalsPath || config['globals-path'] || null;
-  manageFontImports(resolvedOutputPath, sourcePackages, customCssPath, globalsPathOverride);
+  const globalsResult = manageFontImports(
+    resolvedOutputPath,
+    sourcePackages,
+    customCssPath,
+    globalsPathOverride,
+    { strict: Boolean(options.strict) }
+  );
 
   console.log(MESSAGES.SUCCESS);
+  return { globalsResult };
 }
 
 // スクリプトが直接実行された場合のみメイン処理を実行

package/lib/setup.js

@@ -456,13 +456,31 @@ function runAssistantGuard(cwd, packageJsonPath, options, assistantConfig) {
   };
 }
 
-function runGenerate({ skipGenerate, dryRun }) {
+function runGenerate({ skipGenerate, dryRun, strict }) {
+  // --skip-generate / --dry-run と --strict が同時指定された場合、strict チェックを
+  // 走らせる対象 (generate) そのものがスキップされるため strict は事実上無意味。
+  // サイレントに無効化するとユーザーが CI で気付けないので警告を出す。
+  // en: --strict has no effect if generate is skipped — warn the user rather
+  // than silently no-op, which would mask CI misconfiguration.
+  if (strict && (skipGenerate || dryRun)) {
+    console.warn(
+      '⚠️  --strict は generate の失敗のみ検出します。--skip-generate / --dry-run と併用した場合は strict チェックは走りません。'
+    );
+  }
   if (skipGenerate || dryRun) return { skipped: true, ran: false };
   try {
     console.log('🎨 sparkle-design.css を生成中...');
-    generateCSS();
-    return { skipped: false, ran: true };
+    const result = generateCSS(null, null, null, { strict: Boolean(strict) });
+    return { skipped: false, ran: true, globalsResult: result?.globalsResult };
   } catch (error) {
+    // strict モード、または sparkle.config.json の `globals-path` typo などの
+    // 明示指定 not-found は、非 strict でもユーザーが必ず気付くべきなので
+    // 再 throw する（#33 の挙動を setup 経由でも保つ）。
+    // en: Always re-throw explicit --globals-path typos so `setup` surfaces
+    // them via exit code, matching the behaviour of `generate` directly.
+    if (strict || error.code === 'E_EXPLICIT_GLOBALS_PATH_NOT_FOUND') {
+      throw error;
+    }
     console.warn(`⚠️  generate 実行をスキップしました: ${error.message}`);
     return { skipped: false, ran: false, error: error.message };
   }
@@ -493,7 +511,11 @@ export function setupAssistant(options = {}) {
     { ...options, assistant, dryRun },
     assistantConfig
   );
-  const generate = runGenerate({ skipGenerate: Boolean(options.skipGenerate), dryRun });
+  const generate = runGenerate({
+    skipGenerate: Boolean(options.skipGenerate),
+    dryRun,
+    strict: Boolean(options.strict),
+  });
 
   const summary = {
     assistant,

package/package.json

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