sparkle-design-cli 2.0.4 → 2.0.7-beta.0

package/README.md

@@ -31,6 +31,25 @@ npm install -g sparkle-design-cli
 
 > `npx --yes sparkle-design-cli ...` で都度実行する運用を推奨します（常に最新版が利用されます）。
 
+### リリースチャネル
+
+npm の dist-tag でチャネルを分離しています。通常は latest を使い、品質保証中の変更を試したい場合のみ beta を指定してください。
+
+| チャネル | dist-tag | 用途 | 指定方法 |
+|---------|---------|------|---------|
+| 安定版 | `latest` | 本番運用向け。`npx --yes sparkle-design-cli` は常にこれを取得 | （デフォルト） |
+| Beta | `beta` | 品質保証中の検証用 | `npx --yes sparkle-design-cli@beta` |
+
+```bash
+# beta で setup を試す
+npx --yes sparkle-design-cli@beta setup --assistant claude
+
+# beta で check を試す
+npx --yes sparkle-design-cli@beta check src --strict
+```
+
+Beta バージョンは `X.Y.Z-beta.N` 形式で publish されます。GA（正式版）へ昇格するときは、beta の -beta.N を外した `X.Y.Z` を改めて publish します。
+
 ## 使用方法
 
 ### サブコマンド
@@ -362,6 +381,39 @@ sparkle-design-cli generate --help
 sparkle-design-cli check src --strict
 ```
 
+### リリース手順（メンテナ向け）
+
+npm publish は GitHub Actions (`Publish to npm`) 経由で行います。ローカルから `npm publish` しないでください。
+
+#### 安定版（latest）
+
+1. `main` ブランチに変更をマージ
+2. `package.json` の `version` を SemVer で更新（例: `2.0.6` → `2.1.0`）し、`CHANGELOG.md` に該当セクションを追加
+3. PR をマージ後、Actions の **Publish to npm** を `channel: auto`（または `latest`）で手動実行
+4. workflow は lint / test を流したうえで `npm publish`（dist-tag = latest）を実行
+
+#### Beta（beta）
+
+品質保証中の変更を先行公開したいときに使います。latest には影響しません。
+
+1. `package.json` の `version` を `X.Y.Z-beta.N` 形式に更新（例: `2.1.0-beta.0`、次の beta は `2.1.0-beta.1`）
+2. `CHANGELOG.md` に `[X.Y.Z-beta.N]` セクションを追加
+3. PR をマージ後、Actions の **Publish to npm** を `channel: auto`（または `beta`）で手動実行
+4. workflow が version を判定して `npm publish --tag beta` を実行
+5. 利用者側は `npx --yes sparkle-design-cli@beta ...` で検証
+
+#### Beta から GA（latest）へ昇格
+
+同じ成果物を latest にする場合は、新しい安定版 `X.Y.Z` を publish するか、既存 beta バージョンに latest タグを付け替えます。
+
+```bash
+# 選択肢 A: 新たに X.Y.Z を publish する（推奨）
+#   version を X.Y.Z に更新 → workflow を latest で実行
+
+# 選択肢 B: 既存の X.Y.Z-beta.N に latest タグを付け替える
+npm dist-tag add sparkle-design-cli@X.Y.Z-beta.N latest
+```
+
 ## ライセンス
 
 MIT License - 詳細は [LICENSE](LICENSE) ファイルを参照してください。

package/lib/font-manager.js

@@ -5,7 +5,7 @@
 
 import fs from 'fs';
 import path from 'path';
-import { REGEX, COMMENTS, IMPORTS, MESSAGES, FONT_DEFAULTS } from './constants.js';
+import { REGEX, COMMENTS, IMPORTS, MESSAGES } from './constants.js';
 
 /**
  * sparkle-design.css からフォントの@import文を抽出する
@@ -26,15 +26,6 @@ export function removeFontImportsFromCSS(cssContent) {
   return cssContent.replace(REGEX.FONT_IMPORT_WITH_COMMENT, '');
 }
 
-/**
- * フォントimportブロックを生成する
- * @param {Array<string>} fontImports フォントimport文の配列
- * @returns {string} フォントimportブロック
- */
-function createFontImportBlock(fontImports) {
-  return [COMMENTS.FONT_IMPORT, ...fontImports, ''].join('\n');
-}
-
 /**
  * globals.css から node_modules への相対パスを計算する
  * @param {string} globalsPath globals.css の絶対パス

package/lib/generate-css.js

@@ -332,6 +332,40 @@ function processTemplate(template, config, grayMapping, radiusMapping, colors) {
  * @param {string} cssContent CSS内容
  * @param {string|null} outputPath カスタム出力パス（オプション）
  */
+// 自動検出対象の既知デザインシステムパッケージ。
+// `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',
+];
+
+/**
+ * package.json の dependencies / devDependencies から既知のデザインシステムパッケージを検出する。
+ * - `sparkle-design` が入っていれば（CLI のデフォルトで @source に含まれるため）空配列を返し、@source 挿入を有効化
+ * - `@goodpatch/sparkle-design-internal` など追加の既知パッケージが入っていればリストに含める
+ * - いずれも見つからなければ null（従来通り @source を生成しない）
+ * en: Scan package.json and surface source-packages when a design-system package is present.
+ */
+function detectSourcePackagesFromPackageJson(cwd = process.cwd()) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+    const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+
+    const hasDefault = Object.prototype.hasOwnProperty.call(deps, 'sparkle-design');
+    const extras = KNOWN_DESIGN_SYSTEM_PACKAGES.filter((name) =>
+      Object.prototype.hasOwnProperty.call(deps, name)
+    );
+
+    if (hasDefault || extras.length > 0) {
+      return extras;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
 function writeCSS(cssContent, outputPath = null) {
   // カスタムパスが指定されていない場合は実行場所からsrc/appディレクトリに出力
   const defaultOutputPath = path.resolve(
@@ -395,8 +429,19 @@ export function generateCSS(configPath = null, outputPath = null, globalsPath =
   writeSparkleHead(sparkleHeadContent, resolvedOutputPath);
 
   // 8. フォント管理の自動処理を実行（globals.css にはフォント @import を差し込まない）
+  // source-packages は以下の合成で決まる:
+  //   1. package.json から既知のデザインシステムパッケージを自動検出（baseline）
+  //   2. config の extend.source-packages（ユーザー追記分、例: クライアント固有パッケージ）
+  // 両方空なら null（@source を生成しない）。
+  // en: source-packages are resolved by merging auto-detection (from package.json)
+  //     with explicit config entries. If neither surfaces anything, @source is skipped.
   console.log(MESSAGES.FONT_MANAGEMENT_START);
-  const sourcePackages = 'source-packages' in config ? (config['source-packages'] || []) : null;
+  const detectedPackages = detectSourcePackagesFromPackageJson();
+  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);
@@ -414,6 +459,7 @@ export {
   // メイン関数
   processTemplate,
   writeCSS,
+  detectSourcePackagesFromPackageJson,
   // ファイル読み込み
   loadConfig,
   loadTemplate,

package/lib/setup.js

@@ -5,10 +5,16 @@ import { generateCSS } from './generate-css.js';
 
 // デフォルトの sparkle.config.json テンプレート
 // en: Default sparkle.config.json template
+// sparkle-design 本体の既定値（BIZ UDPGothic / BIZ UDGothic）に揃えておくことで、
+// README やドキュメントサイトと見た目が一致する状態で初回セットアップが完了する。
+// @source ディレクティブの生成は generate 側が package.json から既知のデザインシステム
+// パッケージ（sparkle-design / @goodpatch/sparkle-design-internal 等）を自動検出して
+// 行うため、ここで extend.source-packages を指定する必要はない。独自パッケージを
+// 追加する場合のみユーザーが extend.source-packages に追記する。
 const DEFAULT_SPARKLE_CONFIG = {
   primary: 'blue',
-  'font-pro': 'Inter',
-  'font-mono': 'JetBrains Mono',
+  'font-pro': 'BIZ UDPGothic',
+  'font-mono': 'BIZ UDGothic',
   radius: 'md',
 };
 
@@ -70,7 +76,6 @@ function buildCheckScript(target, mode) {
   return `npx --yes sparkle-design-cli check ${target} ${trailingArgs}`;
 }
 
-
 function ensureDir(filePath) {
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
 }
@@ -187,9 +192,11 @@ function buildInstructionBlock(target, assistant) {
     BLOCK_START,
     heading,
     '',
-    '- Run `lint:sparkle` when Sparkle Design changes are involved.',
+    '- **必ず実行**: UI コンポーネントを作成・変更した後は、終了前に `lint:sparkle` を実行してください。Sparkle Design のアンチパターンを検出します。',
+    '- **Required**: After creating or modifying any UI component, run `lint:sparkle` before finishing. This catches Sparkle Design anti-patterns.',
     `- For AI review, prefer \`lint:sparkle:json\` or run \`npx --yes sparkle-design-cli check ${target} --format json\` directly.`,
-    '- Always inspect both `findings` and `manualReviewReminders` from the JSON output.',
+    '- JSON 出力の `findings` に加えて、**`manualReviewReminders` の内容も必ず 1 項目ずつ確認**してください。機械検出できない Badge/Tag の使い分けなどが含まれます。',
+    '- You must inspect every entry in both `findings` and `manualReviewReminders` — the reminders flag judgment calls (Badge vs Tag etc.) that the linter cannot detect.',
     '- If semantic guidance is still needed, consult Sparkle Design docs and JSDoc examples.',
     BLOCK_END,
   ].join('\n');
@@ -222,7 +229,12 @@ function resolveScriptUpdate(existingValue, nextValue, mode, force) {
   }
 
   if (force || isManagedSparkleScript(existingValue, mode)) {
-    return { value: nextValue, changed: true, conflict: false, reason: force ? 'forced' : 'updated' };
+    return {
+      value: nextValue,
+      changed: true,
+      conflict: false,
+      reason: force ? 'forced' : 'updated',
+    };
   }
 
   return { value: existingValue, changed: false, conflict: true, reason: 'preserved-custom' };
@@ -276,7 +288,8 @@ const PM_COMMANDS = {
  */
 function detectPackageManager(cwd) {
   if (fs.existsSync(path.join(cwd, 'pnpm-lock.yaml'))) return 'pnpm';
-  if (fs.existsSync(path.join(cwd, 'bun.lockb')) || fs.existsSync(path.join(cwd, 'bun.lock'))) return 'bun';
+  if (fs.existsSync(path.join(cwd, 'bun.lockb')) || fs.existsSync(path.join(cwd, 'bun.lock')))
+    return 'bun';
   if (fs.existsSync(path.join(cwd, 'yarn.lock'))) return 'yarn';
   return 'npm';
 }
@@ -285,7 +298,12 @@ function detectPackageManager(cwd) {
  * package.json に未登録のパッケージだけをインストールする
  * en: Install only packages not yet listed in package.json
  */
-function ensurePackagesInstalled(cwd, packageManager, candidates, { dev = false, dryRun = false } = {}) {
+function ensurePackagesInstalled(
+  cwd,
+  packageManager,
+  candidates,
+  { dev = false, dryRun = false } = {}
+) {
   const packageJson = readJson(path.join(cwd, 'package.json'));
   const deps = { ...(packageJson.dependencies ?? {}), ...(packageJson.devDependencies ?? {}) };
   const missing = candidates.filter((pkg) => !Object.prototype.hasOwnProperty.call(deps, pkg));
@@ -352,7 +370,12 @@ function buildScaffoldTargets(cwd) {
     },
     {
       name: 'postcssConfig',
-      candidates: ['postcss.config.mjs', 'postcss.config.js', 'postcss.config.cjs', 'postcss.config.ts'],
+      candidates: [
+        'postcss.config.mjs',
+        'postcss.config.js',
+        'postcss.config.cjs',
+        'postcss.config.ts',
+      ],
       target: 'postcss.config.mjs',
       write: (abs) => fs.writeFileSync(abs, INITIAL_POSTCSS_CONFIG, 'utf8'),
     },
@@ -396,7 +419,10 @@ function runInstall(cwd, packageManager, { skipInstall, dryRun }) {
   return {
     skipped: false,
     sparkle: ensurePackagesInstalled(cwd, packageManager, SPARKLE_PACKAGES, { dryRun }),
-    tailwind: ensurePackagesInstalled(cwd, packageManager, TAILWIND_PACKAGES, { dev: true, dryRun }),
+    tailwind: ensurePackagesInstalled(cwd, packageManager, TAILWIND_PACKAGES, {
+      dev: true,
+      dryRun,
+    }),
   };
 }
 
@@ -411,7 +437,10 @@ function runAssistantGuard(cwd, packageJsonPath, options, assistantConfig) {
     ? normalizePath(cwd, options.target, 'Target path')
     : normalizePath(cwd, detectTarget(cwd), 'Target path');
   const instructionPath = options.instructionsPath
-    ? path.resolve(cwd, normalizePath(cwd, options.instructionsPath, 'Instructions path', { checkParentOnly: true }))
+    ? path.resolve(
+        cwd,
+        normalizePath(cwd, options.instructionsPath, 'Instructions path', { checkParentOnly: true })
+      )
     : path.resolve(cwd, assistantConfig.path);
 
   const packageResult = updatePackageJson(packageJsonPath, target, force);
@@ -461,9 +490,17 @@ export function setupAssistant(options = {}) {
   const dryRun = Boolean(options.dryRun);
   const packageManager = detectPackageManager(cwd);
 
-  const install = runInstall(cwd, packageManager, { skipInstall: Boolean(options.skipInstall), dryRun });
+  const install = runInstall(cwd, packageManager, {
+    skipInstall: Boolean(options.skipInstall),
+    dryRun,
+  });
   const scaffold = runScaffold(cwd, { skipScaffold: Boolean(options.skipScaffold), dryRun });
-  const guard = runAssistantGuard(cwd, packageJsonPath, { ...options, assistant, dryRun }, assistantConfig);
+  const guard = runAssistantGuard(
+    cwd,
+    packageJsonPath,
+    { ...options, assistant, dryRun },
+    assistantConfig
+  );
   const generate = runGenerate({ skipGenerate: Boolean(options.skipGenerate), dryRun });
 
   const summary = {
@@ -493,5 +530,45 @@ export function setupAssistant(options = {}) {
   };
 
   console.log(JSON.stringify(summary, null, 2));
+
+  // セットアップ後のリマインダー。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);
+
   return summary;
 }
+
+// 検出した package manager に応じて `lint:sparkle` を呼び出すコマンドを返す。
+// en: Returns the shell invocation for the `lint:sparkle` script based on the
+// detected package manager.
+function buildLintCommand(packageManager) {
+  switch (packageManager) {
+    case 'pnpm':
+      return 'pnpm lint:sparkle';
+    case 'yarn':
+      return 'yarn lint:sparkle';
+    case 'bun':
+      return 'bun run lint:sparkle';
+    case 'npm':
+    default:
+      return 'npm run lint:sparkle';
+  }
+}
+
+function printPostSetupReminder(target, packageManager) {
+  const lintTarget = target || 'src';
+  const lintCmd = buildLintCommand(packageManager);
+  const lines = [
+    '',
+    '📝 次のステップ / Next steps:',
+    `  1. UI コンポーネントを作成・変更したら、必ず \`${lintCmd}\` (または \`npx --yes sparkle-design-cli check ${lintTarget} --strict\`) を実行してください。`,
+    '     After creating or modifying UI components, always run `lint:sparkle` to catch Sparkle Design anti-patterns.',
+    '  2. AI でレビューする場合は `lint:sparkle:json` を使い、`findings` に加えて `manualReviewReminders` の各項目まで必ず確認してください。',
+    '     For AI review, use `lint:sparkle:json` and inspect every entry of both `findings` and `manualReviewReminders`.',
+    '',
+  ];
+  for (const line of lines) {
+    console.error(line);
+  }
+}

package/package.json

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