sparkle-design-cli 2.2.0 → 2.2.1

package/bin/sparkle-design.js

@@ -174,7 +174,9 @@ Setup:
 Generate options:
   -h, --help                 このヘルプメッセージを表示
   -c, --config <path>        設定ファイルのパス (default: ./sparkle.config.json)
-  -o, --output <path>        出力ファイルのパス (default: ./src/app/sparkle-design.css)
+  -o, --output <path>        出力ファイルのパス
+                             (default: globals-path 指定時はその entry CSS と同じ
+                              ディレクトリ、未指定時は ./src/app/sparkle-design.css)
   --globals-path <path>      Tailwind エントリポイント CSS のパス (default: 自動検出)
   --strict                   globals.css への @source 注入等が失敗したら exit 1
                              (CI 向け。既定は warn + 継続で後方互換を維持)

package/lib/font-manager.js

@@ -259,9 +259,10 @@ function reconstructGlobalsCss(globalsContent, sparkleImportBlock, tailwindInfo)
  * @param {string} globalsPath globals.cssのパス
  * @param {Array<string>|null} sourcePackages 追加パッケージ名の配列（null の場合は @source を生成しない）
  * @param {string|null} customCssPath custom-css ファイルの相対パス
- * @returns {{ status: 'skipped' | 'updated' | 'failed', reason?: string }}
+ * @returns {{ status: 'skipped' | 'updated' | 'failed', reason?: string, globalsPath?: string, sourcePackages?: Array<string>|null }}
  *   skipped: 触る理由がない (fonts/sourcePackages/customCss すべて空)
- *   updated: globals.css を正常に書き換えた
+ *   updated: globals.css を正常に書き換えた（patch した globalsPath と挿入した
+ *            sourcePackages を併せて返す — issue #56 のサマリ表示用）
  *   failed: 書き換え対象だったが失敗した (TAILWIND_IMPORT 欠落、write 失敗等)
  */
 export function updateGlobalsWithFonts(
@@ -342,7 +343,11 @@ export function updateGlobalsWithFonts(
     // 6. 更新したglobals.cssを書き込む
     fs.writeFileSync(globalsPath, reconstructedContent, 'utf8');
     console.log(MESSAGES.GLOBALS_UPDATED(globalsPath));
-    return { status: 'updated' };
+    // `globalsPath` / `sourcePackages` は generate のサマリ出力（issue #56）が
+    // 「どの entry CSS に何の @source を挿入したか」を表示するために返す。
+    // en: Surface which entry CSS was patched and with which @source packages
+    // so the caller can render the generate summary (issue #56).
+    return { status: 'updated', globalsPath, sourcePackages };
   } catch (error) {
     // `E_UNSAFE_RELATIVE_PATH`（custom-css の path traversal 等）や
     // `E_TAILWIND_IMPORT_PREPEND_FAILED`（内部不整合）は silent fallback
@@ -564,7 +569,9 @@ function resolveGlobalsPath(sparkleDesignPath, explicitGlobalsPath = null) {
  * @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 }}
+ * @returns {{ status: 'skipped' | 'updated' | 'failed', reason?: string, globalsPath?: string, sourcePackages?: Array<string>|null }}
+ *   updated のときは patch した entry CSS の globalsPath と挿入した sourcePackages
+ *   を含む（issue #56 の generate サマリ用）。
  */
 export function manageFontImports(
   sparkleDesignPath,

package/lib/generate-css.js

@@ -23,6 +23,7 @@ import {
   updateGlobalsWithFonts,
   isViteProject,
 } from './font-manager.js';
+import { assertSafeRelativePath, toPosixPath } from './path-utils.js';
 
 /**
  * config の extend セクションを解決する
@@ -344,6 +345,7 @@ function writeSparkleHead(content, sparkleDesignCssPath) {
   fs.writeFileSync(outputPath, content, 'utf8');
   console.log(`✅ SparkleHead.tsx を生成しました: ${outputPath}`);
   console.log('   → ルートレイアウトの <head> 内に <SparkleHead /> を追加してください');
+  return outputPath;
 }
 
 const VITE_INDEX_HTML_BLOCK_START = '<!-- sparkle-design-cli:fonts:start -->';
@@ -602,6 +604,73 @@ function detectSourcePackagesFromPackageJson(cwd = process.cwd()) {
   return null;
 }
 
+/**
+ * `--output` 未指定時に、明示された globals-path（CLI `--globals-path` または
+ * `extend.globals-path`）と同じディレクトリを出力先に使えるか判定する。
+ *
+ * 以前は framework に依らず常に `DEFAULT_OUTPUT_DIR = src/app/` に書き出していた
+ * ため、Vite の `src/index.css` 構成で `globals-path: src/index.css` を指定しても
+ * `sparkle-design.css` が `src/app/` に落ち、本来不要な `src/app/` ディレクトリが
+ * 生成されてレビュー / クリーンアップを混乱させていた（issue #56 確定バグ）。
+ *
+ * - globals-path が未指定なら null（従来どおり src/app/ を使う）
+ * - 不正な path（traversal / shell メタ文字 / 絶対パス）は `assertSafeRelativePath`
+ *   が throw（後段 `resolveGlobalsPath` でも同様に弾かれるので早期 fail-loud）
+ * - 解決した path が実在しなければ null。実在しない globals-path は
+ *   `manageFontImports` が `E_EXPLICIT_GLOBALS_PATH_NOT_FOUND` で loud に throw
+ *   するので、ここで typo 由来の誤ディレクトリを掘らないよう存在チェックする
+ * - 実在しても**通常ファイルでない**（ディレクトリ等）なら null。例えば
+ *   `globals-path: src` のようにディレクトリを誤指定すると、存在チェックだけ
+ *   では通過し `path.dirname('.../src')` がプロジェクト root を指して出力先が
+ *   root に誤誘導される。entry CSS は CSS ファイル前提なので `isFile()` で弾く。
+ *
+ * en: When `--output` is omitted, return the directory of an explicit
+ * globals-path so sparkle-design.css lands next to the entry CSS instead of
+ * always under src/app/. Returns null (→ keep src/app/ default) when no
+ * globals-path is given, it doesn't exist yet, or it isn't a regular file
+ * (e.g. a directory was passed by mistake).
+ *
+ * @param {string|null} globalsPathOverride
+ * @returns {string|null} entry CSS が通常ファイルとして実在する場合その絶対ディレクトリ、なければ null
+ */
+function resolveGlobalsDirForOutput(globalsPathOverride) {
+  if (!globalsPathOverride) {
+    return null;
+  }
+  assertSafeRelativePath(globalsPathOverride, 'globals-path');
+  const resolved = path.resolve(process.cwd(), globalsPathOverride);
+  let stat;
+  try {
+    stat = fs.statSync(resolved);
+  } catch {
+    // 実在しない（ENOENT 等）。出力先は src/app/ 既定に委ね、entry CSS の
+    // not-found は manageFontImports が loud に throw する。
+    return null;
+  }
+  if (!stat.isFile()) {
+    return null;
+  }
+  return path.dirname(resolved);
+}
+
+/**
+ * sparkle-design.css の出力先絶対パスを決定する。
+ * 優先順位: `--output` 明示 > globals-path と同じディレクトリ > `src/app/`（既定）
+ * @param {string|null} outputPath `--output` の値
+ * @param {string|null} globalsPathOverride globals-path（CLI > config）
+ * @returns {string} 出力先の絶対パス
+ */
+function resolveOutputPath(outputPath, globalsPathOverride) {
+  if (outputPath) {
+    return path.resolve(outputPath);
+  }
+  const globalsDir = resolveGlobalsDirForOutput(globalsPathOverride);
+  if (globalsDir) {
+    return path.join(globalsDir, 'sparkle-design.css');
+  }
+  return path.resolve(process.cwd(), ...PATHS.DEFAULT_OUTPUT_DIR, 'sparkle-design.css');
+}
+
 function writeCSS(cssContent, outputPath = null) {
   // カスタムパスが指定されていない場合は実行場所からsrc/appディレクトリに出力
   const defaultOutputPath = path.resolve(
@@ -626,6 +695,79 @@ function writeCSS(cssContent, outputPath = null) {
   }
 }
 
+/**
+ * `@source` ブロックに実際に書き出されるパッケージ名一覧を組み立てる。
+ * `createSourceBlock`（font-manager.js）と同じく default の `sparkle-design` を
+ * 先頭に入れ、重複を除いた配列を返す。サマリ表示専用。
+ * en: Mirror createSourceBlock's package list (default sparkle-design first)
+ * for the summary output.
+ * @param {Array<string>|null|undefined} sourcePackages
+ * @returns {Array<string>|null} null は @source 未挿入
+ */
+function describeInsertedSourcePackages(sourcePackages) {
+  if (sourcePackages === null || sourcePackages === undefined) {
+    return null;
+  }
+  const defaultPackage = 'sparkle-design';
+  return [defaultPackage, ...sourcePackages.filter((p) => p !== defaultPackage)];
+}
+
+/**
+ * generate 完了時に「何を・どこに書いたか」を 1 ブロックで要約出力する。
+ * issue #56 の可観測性要求への対応。とくに entry CSS と出力先のディレクトリが
+ * 乖離している場合（Vite で `src/index.css` を patch しつつ出力が `src/app/` に
+ * 落ちる等）に警告を出し、`@source` が想定どおり挿入されたかを目視確認できる
+ * ようにする。
+ * en: Print a one-block summary of what `generate` patched / wrote and warn
+ * when the entry CSS dir and the output dir diverge (issue #56 observability).
+ *
+ * @param {Object} args
+ * @param {string} args.outputPath sparkle-design.css の絶対パス
+ * @param {string} args.sparkleHeadPath SparkleHead.tsx の絶対パス
+ * @param {{ status: string, reason?: string, globalsPath?: string, sourcePackages?: Array<string>|null }} args.globalsResult
+ */
+function printGenerateSummary({ outputPath, sparkleHeadPath, globalsResult }) {
+  const cwd = process.cwd();
+  const rel = (p) => (p ? path.relative(cwd, p) || '.' : null);
+  const lines = ['', '📋 生成サマリ (issue #56):'];
+  lines.push(`   • sparkle-design.css: ${rel(outputPath)}`);
+  lines.push(`   • SparkleHead.tsx:    ${rel(sparkleHeadPath)}`);
+
+  if (globalsResult.status === 'updated' && globalsResult.globalsPath) {
+    const entryPath = globalsResult.globalsPath;
+    lines.push(`   • パッチした entry CSS: ${rel(entryPath)}`);
+
+    const inserted = describeInsertedSourcePackages(globalsResult.sourcePackages);
+    if (inserted && inserted.length > 0) {
+      lines.push(`   • 挿入した @source:    ${inserted.join(', ')}`);
+    } else {
+      lines.push('   • 挿入した @source:    なし（source-packages 未指定）');
+    }
+
+    const entryDir = path.dirname(entryPath);
+    const outputDir = path.dirname(outputPath);
+    if (path.resolve(entryDir) === path.resolve(outputDir)) {
+      lines.push(`   • entry CSS と出力先 dir: 一致 (${rel(entryDir)})`);
+    } else {
+      const suggestedOutput = toPosixPath(path.join(rel(entryDir), 'sparkle-design.css'));
+      lines.push(
+        `   ⚠️  entry CSS dir (${rel(entryDir)}) と出力先 dir (${rel(outputDir)}) が異なります。`
+      );
+      lines.push(
+        `      @import は相対パスで解決されるため動作はしますが、出力先を揃えるには ` +
+          `--output ${suggestedOutput} の指定、または extend.globals-path と同じ ` +
+          `ディレクトリへの出力を検討してください。`
+      );
+    }
+  } else if (globalsResult.status === 'skipped') {
+    lines.push(`   • entry CSS パッチ:    スキップ (${globalsResult.reason ?? 'no-work'})`);
+  } else if (globalsResult.status === 'failed') {
+    lines.push(`   • entry CSS パッチ:    ❌ 失敗 (${globalsResult.reason ?? 'unknown'})`);
+  }
+
+  console.log(lines.join('\n'));
+}
+
 /**
  * メイン処理
  * @param {string|null} configPath カスタム設定ファイルのパス（オプション）
@@ -666,18 +808,21 @@ export function generateCSS(
     colors
   );
 
+  // globals-path（CLI `--globals-path` > `extend.globals-path`）を先に解決する。
+  // 出力先デフォルトの決定とフォント管理（@source 挿入）の両方で同じ値を使う。
+  // en: Resolve globals-path once (CLI over config); both the default output
+  // location and the font-import patcher consume it.
+  const globalsPathOverride = globalsPath || config['globals-path'] || null;
+
   // 6. CSSファイルを書き出し
-  const defaultOutputPath = path.resolve(
-    process.cwd(),
-    ...PATHS.DEFAULT_OUTPUT_DIR,
-    'sparkle-design.css'
-  );
-  const resolvedOutputPath = outputPath ? path.resolve(outputPath) : defaultOutputPath;
-  writeCSS(processedCSS, outputPath);
+  // `--output` 未指定時は globals-path と同じディレクトリ（実在する場合）に出す。
+  // 詳細は resolveOutputPath / resolveGlobalsDirForOutput の comment 参照（#56）。
+  const resolvedOutputPath = resolveOutputPath(outputPath, globalsPathOverride);
+  writeCSS(processedCSS, resolvedOutputPath);
 
   // 7. SparkleHead.tsx を生成（processTemplate で解決済みの resolvedFonts を再利用）
   const sparkleHeadContent = generateSparkleHeadContent(resolvedFonts);
-  writeSparkleHead(sparkleHeadContent, resolvedOutputPath);
+  const sparkleHeadPath = writeSparkleHead(sparkleHeadContent, resolvedOutputPath);
 
   // 7.5 Vite プロジェクトの index.html に Sparkle のフォント <link> タグを upsert
   // する。Vite は <head> が index.html 側にあるため、React コンポーネントの
@@ -740,7 +885,6 @@ export function generateCSS(
       ? [...new Set([...(detectedPackages ?? []), ...(explicitPackages ?? [])])]
       : null;
   const customCssPath = config['custom-css'] || null;
-  const globalsPathOverride = globalsPath || config['globals-path'] || null;
   const globalsResult = manageFontImports(
     resolvedOutputPath,
     sourcePackages,
@@ -749,6 +893,11 @@ export function generateCSS(
     { strict: Boolean(options.strict) }
   );
 
+  // 9. 生成サマリ（可観測性 / issue #56）。何を・どこに書いたか、@source が
+  //    挿入されたか、entry CSS と出力先の dir が乖離していないかを 1 ブロックで
+  //    出力する。設定は正しいのに @source が silent に落ちる事象を即検知できる。
+  printGenerateSummary({ outputPath: resolvedOutputPath, sparkleHeadPath, globalsResult });
+
   console.log(MESSAGES.SUCCESS);
   return { globalsResult };
 }

package/package.json

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