sparkle-design-cli 2.5.0-beta.6 → 2.5.0-beta.7

package/README.md

@@ -79,6 +79,9 @@ npx --yes sparkle-design-cli migrate
 
 # Artifact Registry の npm registry 用トークンを ~/.npmrc に書く（beta）
 npx --yes sparkle-design-cli@beta auth
+
+# @goodpatch の取得元を GitHub Packages から Artifact Registry へ切り替える（beta。既定は dry-run）
+npx --yes sparkle-design-cli@beta migrate-registry
 ```
 
 ### generate: 基本的な使用方法
@@ -238,6 +241,49 @@ pnpm install
 - トークンは Artifact Registry（`<location>-npm.pkg.dev`）以外には書きません。`cloud-platform` スコープの Google トークンなので、ほかのホストに渡すと資格情報の漏えいになるためです
 - トークンを画面に出さず、refresh token などの長期クレデンシャルもコピーしません（gcloud の管理下に置いたまま）
 
+#### CI の中で使う（`--ci`）
+
+GitHub Actions と Vercel のビルドでは、`--ci` を付けると gcloud なしで認証できます。ビルド環境が発行する OIDC トークンを、Workload Identity Federation（STS）で AR のアクセストークンに交換します。長期のトークンを secrets に置く必要はありません。
+
+```yaml
+# GitHub Actions
+permissions:
+  contents: read
+  id-token: write
+steps:
+  - uses: actions/checkout@v4 # プロジェクトの .npmrc から registry を読むので必要
+  - uses: actions/setup-node@v4 # registry-url は付けない
+  - run: npx --yes sparkle-design-cli@beta auth --ci # install の直前に置く
+  - run: pnpm install --frozen-lockfile
+```
+
+```bash
+# Vercel の Install Command（Settings → Security で OIDC federation を有効にし、Issuer Mode を Team にする）
+npx --yes sparkle-design-cli@beta auth --ci && pnpm install --frozen-lockfile
+```
+
+- Sparkle の registry では、使う WIF プロバイダを CLI が知っています。受け付けるのは goodpatch org の GitHub Actions と、Vercel の sparkle-design チームのビルドです。別の registry では `--provider` でプロバイダを指定します
+- サービスアカウントは経由しません。AR の IAM に付けた principalSet で認可されます
+- **GitHub Actions では、トークンは数分で失効します。** 交換したトークンの寿命は、元になる GitHub の OIDC トークンの残り時間（発行から約 5 分）までです。`auth --ci` は install の直前に置いてください。Vercel の OIDC トークンは約 60 分あります
+
+### migrate-registry: GitHub Packages から Artifact Registry への切り替え（beta）
+
+既存プロジェクトの `@goodpatch` の取得元を AR に切り替えます。既定は dry-run で、`--write` を付けたときだけ書き換えます。
+
+```bash
+npx --yes sparkle-design-cli@beta migrate-registry           # 変更内容と、手で直す箇所を表示
+npx --yes sparkle-design-cli@beta migrate-registry --write   # .npmrc と lockfile を書き換える
+npx --yes sparkle-design-cli@beta auth
+pnpm install --frozen-lockfile
+```
+
+- **書き換えるもの:**
+  - プロジェクトの `.npmrc`: `@goodpatch:registry` を AR に向けます。使われなくなる GitHub Packages の認証行も消します
+  - lockfile: `pnpm-lock.yaml` は GitHub Packages の `tarball:` を外し、`package-lock.json` は `resolved` を AR の URL に置き換えます。lockfile には取得元の URL が記録されているので、`.npmrc` だけを変えても frozen install は GitHub Packages に取りに行き、401 で落ちます
+  - integrity は変わりません。AR には GitHub Packages と同じ tarball を置いています
+- **書き換えないもの:** GitHub Actions のワークフロー、`vercel.json`、yarn の設定。GitHub Packages を前提にしている箇所の一覧と、置き換え後の形を表示します
+- AR に無い `@goodpatch` パッケージを使っているプロジェクトでは止まります。スコープごと切り替えると、それらが取得できなくなるためです。影響を承知のうえで続けるときは `--force` を付けます
+
 ### setup: プロジェクトのフルセットアップ
 
 `sparkle-design-cli setup` は、Sparkle Design の導入に必要な作業をまとめて行います：

package/bin/sparkle-design.js

@@ -9,6 +9,7 @@ import { loadAntiPatternPlugins } from '../lib/load-plugins.js';
 import { runRules } from '../lib/rules-report.js';
 import { runAuth } from '../lib/auth.js';
 import { runMigrate } from '../lib/migrate.js';
+import { runMigrateRegistry } from '../lib/migrate-registry.js';
 
 const SUBCOMMANDS = new Set([
   'generate',
@@ -17,6 +18,7 @@ const SUBCOMMANDS = new Set([
   'migrate',
   'setup',
   'auth',
+  'migrate-registry',
   'stop-hook',
   'plugin-spec',
 ]);
@@ -237,7 +239,7 @@ function parseMigrateOptions(args) {
  * en: Unknown flags fail fast, same as the other subcommands.
  */
 function parseAuthOptions(args) {
-  const options = { registry: null, help: false };
+  const options = { registry: null, ci: false, provider: null, help: false };
 
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
@@ -250,12 +252,53 @@ function parseAuthOptions(args) {
       i += 1;
       continue;
     }
+    if (arg === '--ci') {
+      options.ci = true;
+      continue;
+    }
+    if (arg === '--provider') {
+      options.provider = requireOptionValue(args, i, '--provider');
+      i += 1;
+      continue;
+    }
     throw new Error(`Unknown option for auth: ${arg}`);
   }
 
   return options;
 }
 
+/**
+ * `migrate-registry` のオプション。既定は dry-run で、--write のときだけ書き換える。
+ * en: Dry-run by default; --write applies the changes.
+ */
+function parseMigrateRegistryOptions(args) {
+  const options = { registry: null, write: false, force: false, help: false };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '-h' || arg === '--help') {
+      options.help = true;
+      continue;
+    }
+    if (arg === '--write') {
+      options.write = true;
+      continue;
+    }
+    if (arg === '--force') {
+      options.force = true;
+      continue;
+    }
+    if (arg === '--registry') {
+      options.registry = requireOptionValue(args, i, '--registry');
+      i += 1;
+      continue;
+    }
+    throw new Error(`Unknown option for migrate-registry: ${arg}`);
+  }
+
+  return options;
+}
+
 function showHelp() {
   console.log(`
 Sparkle Design CLI
@@ -270,6 +313,9 @@ Commands:
   migrate      旧セマンティックトークンを新トークンへ移行（既定は dry-run。--write で書き換え）
   setup        Sparkle Design プロジェクトをセットアップ（パッケージ導入 + 初期ファイル + AI ガード + generate）
   auth         Artifact Registry の npm registry 用アクセストークンを ~/.npmrc に書く（beta）
+  migrate-registry
+               @goodpatch の取得元を GitHub Packages から Artifact Registry へ切り替える
+               （.npmrc と lockfile。既定は dry-run。--write で書き換え）
   stop-hook    AI assistant の Stop hook 用 internal subcommand（severity=error の findings か、
                実行に失敗して未検査のルールがあるときに exit 2 で 1 度だけ停止をブロック / 再発火は自動回避。
                warning / info はブロックせず件数の要約を stderr に出す）
@@ -308,6 +354,11 @@ Plugin spec:
 Auth (beta):
   sparkle-design-cli auth                  # プロジェクトの .npmrc の @goodpatch:registry を対象に認証
   sparkle-design-cli auth --registry https://asia-northeast1-npm.pkg.dev/<project>/<repository>/
+  sparkle-design-cli auth --ci             # GitHub Actions / Vercel のビルド内で（OIDC で認証）
+
+Migrate registry:
+  sparkle-design-cli migrate-registry           # 変更内容を表示するだけ（dry-run）
+  sparkle-design-cli migrate-registry --write   # .npmrc と lockfile を書き換える
 
 Setup:
   sparkle-design-cli setup                                        # フルセットアップ（推奨・新規導入時）
@@ -414,6 +465,11 @@ Migrate の分類:
 Auth options:
   -h, --help                 このヘルプメッセージを表示
   --registry <url>           対象の registry（default: プロジェクトの .npmrc の @goodpatch:registry）
+  --ci                       CI の中で使う。GitHub Actions（permissions: id-token: write）または
+                             Vercel（OIDC federation を Team issuer で有効化）の OIDC トークンを
+                             Workload Identity Federation で交換する。gcloud は不要
+  --provider <name>          --ci で使う WIF プロバイダ（//iam.googleapis.com/projects/<番号>/...）。
+                             Sparkle の registry では既定値があるので不要
 
 Auth の動作:
   1. Google の資格情報（ADC → gcloud auth print-access-token の順）からアクセストークンを取得
@@ -424,6 +480,21 @@ Auth の動作:
   トークンは Artifact Registry（<location>-npm.pkg.dev）にだけ書き、画面には出しません。
   refresh token などの長期クレデンシャルは gcloud の管理下に置いたままで、コピーしません。
 
+Migrate registry options:
+  -h, --help                 このヘルプメッセージを表示
+  --write                    実際に書き換える（指定しなければ dry-run）
+  --registry <url>           移行先（default: Sparkle の Artifact Registry）
+  --force                    Artifact Registry に無い @goodpatch パッケージがあっても続行する
+
+Migrate registry の動作:
+  1. プロジェクトの .npmrc の @goodpatch:registry を Artifact Registry に向け、
+     使われなくなる GitHub Packages の認証行を消す
+  2. lockfile に記録された GitHub Packages の tarball URL を外す / 置き換える
+     （pnpm-lock.yaml は tarball を外し integrity を残す。package-lock.json は resolved を置き換える）
+     そのままだと .npmrc を変えても frozen install が GitHub Packages に取りに行き 401 になる
+  3. GitHub Actions のワークフロー・vercel.json・yarn の設定で GitHub Packages を前提に
+     している箇所を一覧にする（書き換えない。対処例を表示する）
+
 Setup options:
   -h, --help                 このヘルプメッセージを表示
   --assistant <name>         claude / codex / cursor / generic (default: generic)
@@ -570,6 +641,16 @@ async function main() {
       return;
     }
 
+    if (command === 'migrate-registry') {
+      const options = parseMigrateRegistryOptions(args.slice(1));
+      if (options.help) {
+        showHelp();
+        process.exit(0);
+      }
+      await runMigrateRegistry(options);
+      return;
+    }
+
     if (command === 'stop-hook') {
       // setup で各 agent の hook 設定ファイルから呼ばれる internal subcommand。
       // 以降の引数はすべて lint 対象 path。setup が書き出す hook は 1 つだが、

package/lib/auth.js

@@ -22,6 +22,31 @@ import { URL, URLSearchParams } from 'url';
 const SCOPE = '@goodpatch';
 const GOOGLE_TOKEN_URL = 'https://oauth2.googleapis.com/token';
 const GOOGLE_TOKENINFO_URL = 'https://oauth2.googleapis.com/tokeninfo';
+const STS_TOKEN_URL = 'https://sts.googleapis.com/v1/token';
+
+/**
+ * Sparkle の本番 registry（goodpatch/sparkle-design-internal#261）。
+ * en: Production Artifact Registry for Sparkle packages.
+ */
+export const DEFAULT_REGISTRY =
+  'https://asia-northeast1-npm.pkg.dev/gp-sparkle-design/sparkle-npm/';
+
+/**
+ * `auth --ci` で使う Workload Identity Federation のプロバイダ。registry ごとに持ち、
+ * ここに無い registry では `--provider` の指定を必須にする（他の GCP プロジェクトの
+ * registry に、Sparkle 用のプロバイダで交換したトークンを書かないため）。
+ * - github: goodpatch org（repository_owner_id）の GitHub Actions だけを受け入れる
+ * - vercel: Vercel の sparkle-design チームのビルドだけを受け入れる
+ * en: WIF providers per registry. Unknown registries require --provider.
+ */
+export const KNOWN_WIF_PROVIDERS = {
+  [DEFAULT_REGISTRY]: {
+    github:
+      '//iam.googleapis.com/projects/339424476445/locations/global/workloadIdentityPools/github/providers/goodpatch',
+    vercel:
+      '//iam.googleapis.com/projects/339424476445/locations/global/workloadIdentityPools/vercel/providers/sparkle-design',
+  },
+};
 /** アクセストークンとして受け付ける文字。改行などで .npmrc に別の行を差し込ませない */
 const TOKEN_PATTERN = /^[A-Za-z0-9._\-~+/=]+$/;
 
@@ -197,6 +222,142 @@ function tokenFromGcloud({ spawn }) {
   return token ? { token, expiresIn: null, via: 'gcloud' } : null;
 }
 
+// ---- CI（auth --ci）: OIDC トークン → STS ----
+
+/**
+ * CI の実行環境を判別する。
+ * - GitHub Actions: OIDC トークンの発行 URL が渡されていること（`permissions: id-token: write`）
+ * - Vercel: ビルド時の `VERCEL_OIDC_TOKEN`（プロジェクト設定で OIDC を有効にしたとき）
+ * 判別できないときは、足りない設定を含めた理由を返す。
+ * en: Detect the CI environment, or explain what is missing.
+ */
+export function detectCiEnvironment(env) {
+  if (env.ACTIONS_ID_TOKEN_REQUEST_URL && env.ACTIONS_ID_TOKEN_REQUEST_TOKEN) {
+    return { kind: 'github' };
+  }
+  if (env.VERCEL_OIDC_TOKEN) {
+    return { kind: 'vercel' };
+  }
+  if (env.GITHUB_ACTIONS === 'true') {
+    return {
+      kind: null,
+      reason:
+        'GitHub Actions で OIDC トークンを取得できません。ジョブに次の権限を足してください:\n' +
+        '   permissions:\n' +
+        '     id-token: write\n' +
+        '     contents: read',
+    };
+  }
+  if (env.VERCEL === '1') {
+    return {
+      kind: null,
+      reason:
+        'Vercel のビルドで VERCEL_OIDC_TOKEN がありません。プロジェクトの Settings → Security で\n' +
+        '   Secure backend access with OIDC federation を有効にし、Issuer Mode を Team にしてください。',
+    };
+  }
+  return {
+    kind: null,
+    reason:
+      'CI の実行環境（GitHub Actions / Vercel）を判別できません。\n' +
+      '   ローカルでは --ci を付けずに sparkle-design-cli auth を実行してください。',
+  };
+}
+
+/** WIF プロバイダのリソース名（`//iam.googleapis.com/projects/<番号>/.../providers/<id>`）を検証する */
+export function normalizeWifProvider(raw) {
+  const value = String(raw)
+    .trim()
+    .replace(/^https:/, '');
+  if (
+    !/^\/\/iam\.googleapis\.com\/projects\/\d+\/locations\/global\/workloadIdentityPools\/[a-z0-9-]+\/providers\/[a-z0-9-]+$/.test(
+      value
+    )
+  ) {
+    throw new AuthError(
+      `WIF プロバイダの形式ではありません: ${raw}\n` +
+        '   //iam.googleapis.com/projects/<プロジェクト番号>/locations/global/workloadIdentityPools/<プール>/providers/<プロバイダ> の形で指定してください。'
+    );
+  }
+  return value;
+}
+
+/** registry と実行環境から、交換に使う WIF プロバイダを決める */
+export function resolveWifProvider(registry, kind, override = null) {
+  if (override) return normalizeWifProvider(override);
+  const known = KNOWN_WIF_PROVIDERS[registry]?.[kind];
+  if (!known) {
+    throw new AuthError(
+      `この registry（${registry}）の ${kind} 用 WIF プロバイダが分かりません。--provider で指定してください。`
+    );
+  }
+  return known;
+}
+
+async function readJson(res) {
+  try {
+    return await res.json();
+  } catch {
+    return {};
+  }
+}
+
+/** GitHub Actions の OIDC トークン。audience は STS が既定で受け付けるプロバイダの https URL */
+async function oidcTokenFromGithub({ env, fetchImpl }, provider) {
+  const url = new URL(env.ACTIONS_ID_TOKEN_REQUEST_URL);
+  url.searchParams.set('audience', `https:${provider}`);
+  const res = await fetchImpl(url.toString(), {
+    headers: { authorization: `bearer ${env.ACTIONS_ID_TOKEN_REQUEST_TOKEN}` },
+  });
+  const json = await readJson(res);
+  if (!res.ok || typeof json.value !== 'string') {
+    throw new AuthError(
+      `GitHub Actions の OIDC トークンを取得できませんでした（HTTP ${res.status}）`
+    );
+  }
+  return json.value;
+}
+
+/**
+ * OIDC トークンを STS で GCP のアクセストークン（federated token）に交換する。
+ * サービスアカウントは経由せず、AR の IAM に付けた principalSet で認可される。
+ * en: Exchange the OIDC token at STS; no service account impersonation.
+ */
+async function exchangeWithSts({ fetchImpl }, provider, subjectToken) {
+  const res = await fetchImpl(STS_TOKEN_URL, {
+    method: 'POST',
+    headers: { 'content-type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({
+      grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange',
+      audience: provider,
+      scope: 'https://www.googleapis.com/auth/cloud-platform',
+      requested_token_type: 'urn:ietf:params:oauth:token-type:access_token',
+      subject_token_type: 'urn:ietf:params:oauth:token-type:jwt',
+      subject_token: subjectToken,
+    }).toString(),
+  });
+  const json = await readJson(res);
+  if (!res.ok || typeof json.access_token !== 'string') {
+    // STS のエラー本文にトークンは含まれない（error / error_description のみ）
+    const detail = [json.error, json.error_description].filter(Boolean).join(': ');
+    throw new AuthError(
+      `STS でのトークン交換に失敗しました（HTTP ${res.status}${detail ? ` ${detail}` : ''}）。\n` +
+        '   WIF プロバイダの条件（リポジトリの owner / Vercel のチーム）を満たしているか確認してください。'
+    );
+  }
+  return { token: json.access_token, expiresIn: Number(json.expires_in) || null };
+}
+
+async function tokenFromCi(d, registry, providerOverride) {
+  const ci = detectCiEnvironment(d.env);
+  if (!ci.kind) throw new AuthError(ci.reason);
+  const provider = resolveWifProvider(registry, ci.kind, providerOverride);
+  const subjectToken =
+    ci.kind === 'github' ? await oidcTokenFromGithub(d, provider) : d.env.VERCEL_OIDC_TOKEN;
+  const exchanged = await exchangeWithSts(d, provider, subjectToken);
+  return { ...exchanged, via: ci.kind === 'github' ? 'GitHub Actions の OIDC' : 'Vercel の OIDC' };
+}
+
 /** 失効までの秒数を tokeninfo で調べる（取れなくても認証自体は成功扱い） */
 async function lookupExpiresIn(token, fetchImpl) {
   try {
@@ -249,7 +410,12 @@ export async function runAuth(options = {}, deps = {}) {
   }
   const registry = normalizeRegistry(rawRegistry);
 
-  const acquired = (await tokenFromAdc(d)) ?? tokenFromGcloud(d);
+  if (!options.ci && options.provider) {
+    throw new AuthError('--provider は --ci と組み合わせて使います。');
+  }
+  const acquired = options.ci
+    ? await tokenFromCi(d, registry, options.provider)
+    : ((await tokenFromAdc(d)) ?? tokenFromGcloud(d));
   if (!acquired) {
     throw new AuthError(
       'Google の認証情報が見つからないか、期限切れです。次を実行してから、もう一度 auth を実行してください:\n' +

package/lib/migrate-registry.js

@@ -0,0 +1,390 @@
+import fs from 'fs';
+import path from 'path';
+import { URL } from 'url';
+import { DEFAULT_REGISTRY, normalizeRegistry } from './auth.js';
+
+/**
+ * `sparkle-design-cli migrate-registry` — `@goodpatch/sparkle-design-internal` の取得元を
+ * GitHub Packages から Google Artifact Registry（AR）へ切り替える
+ * （goodpatch/sparkle-design-internal#261）。
+ *
+ * 書き換えるのは「誰がやっても同じ結果になる」ものだけ:
+ * - プロジェクトの `.npmrc`（`@goodpatch:registry` を AR に向ける）
+ * - lockfile に記録された GitHub Packages の tarball URL
+ *   （そのままだと `.npmrc` を変えても frozen install が GitHub Packages に取りに行き 401 になる）
+ *
+ * CI のワークフローや Vercel など、プロジェクトごとに形が違う設定は書き換えず、
+ * 該当箇所と対処を一覧にして返す（判断はスキル / 人が行う）。
+ * en: Rewrites only deterministic files (.npmrc, lockfiles); CI / Vercel settings are
+ *     reported, not edited.
+ */
+
+const SCOPE = '@goodpatch';
+const GITHUB_REGISTRY_HOST = 'npm.pkg.github.com';
+/** AR に移植済みで、スコープごと切り替えても引ける @goodpatch パッケージ */
+export const MIGRATABLE_PACKAGES = new Set(['@goodpatch/sparkle-design-internal']);
+
+export class MigrateRegistryError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'MigrateRegistryError';
+  }
+}
+
+function splitLines(text) {
+  const lines = text === '' ? [] : text.split(/\r?\n/);
+  if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop();
+  return lines;
+}
+
+function parseNpmrcLine(line) {
+  const trimmed = line.trim();
+  if (trimmed === '' || trimmed.startsWith('#') || trimmed.startsWith(';')) return null;
+  const match = /^([^=]+?)\s*=\s*(.*)$/.exec(trimmed);
+  return match ? { key: match[1], value: match[2].trim() } : null;
+}
+
+function isGithubRegistry(value) {
+  try {
+    return new URL(value).host === GITHUB_REGISTRY_HOST;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * プロジェクトの `.npmrc` を書き換える。
+ * - `@goodpatch:registry=` を AR に置き換える（無ければ足す）
+ * - GitHub Packages の認証行（`//npm.pkg.github.com/:_authToken=`）は、他のスコープや既定 registry が
+ *   GitHub Packages を使っていなければ消す（使っていれば残して警告する）
+ */
+export function rewriteNpmrc(text, registry) {
+  const lines = splitLines(text);
+  const changes = [];
+  const warnings = [];
+
+  const othersUseGithub = lines.some((line) => {
+    const parsed = parseNpmrcLine(line);
+    if (!parsed || parsed.key === `${SCOPE}:registry`) return false;
+    return (
+      (parsed.key === 'registry' || parsed.key.endsWith(':registry')) &&
+      isGithubRegistry(parsed.value)
+    );
+  });
+
+  let replaced = false;
+  const next = [];
+  for (const line of lines) {
+    const parsed = parseNpmrcLine(line);
+    if (parsed?.key === `${SCOPE}:registry`) {
+      if (!replaced) {
+        next.push(`${SCOPE}:registry=${registry}`);
+        if (parsed.value !== registry) changes.push(`${SCOPE}:registry を ${registry} に変更`);
+        replaced = true;
+      }
+      continue;
+    }
+    if (parsed && parsed.key.startsWith(`//${GITHUB_REGISTRY_HOST}/`)) {
+      if (othersUseGithub) {
+        warnings.push(
+          `GitHub Packages の認証行（${parsed.key}）は、他のスコープが GitHub Packages を使っているため残しました`
+        );
+        next.push(line);
+      } else {
+        changes.push(`GitHub Packages の認証行（${parsed.key}）を削除`);
+      }
+      continue;
+    }
+    next.push(line);
+  }
+  if (!replaced) {
+    next.push(`${SCOPE}:registry=${registry}`);
+    changes.push(`${SCOPE}:registry=${registry} を追加`);
+  }
+  return { text: `${next.join('\n')}\n`, changes, warnings };
+}
+
+/**
+ * pnpm-lock.yaml の `resolution: {integrity: ..., tarball: https://npm.pkg.github.com/download/@goodpatch/...}`
+ * から tarball を外す。integrity は AR に移植した tarball と同じなので残せば検証は効き、
+ * 取得先は `.npmrc` の registry から決まる（新しく解決した版は pnpm が AR の URL を記録する）。
+ */
+export function rewritePnpmLock(text) {
+  let count = 0;
+  const next = text.replace(
+    /, tarball: https:\/\/npm\.pkg\.github\.com\/download\/@goodpatch\/[^}\s]+(?=})/g,
+    () => {
+      count += 1;
+      return '';
+    }
+  );
+  return { text: next, count };
+}
+
+/**
+ * package-lock.json の `resolved` を AR の tarball URL に置き換える。npm は registry を
+ * 変えても lockfile の `resolved` に取りに行く（読み替えるのは registry.npmjs.org だけ）ため。
+ * JSON を組み直さず文字列で置き換えて、整形を保つ。
+ */
+export function rewritePackageLock(text, registry) {
+  let count = 0;
+  const next = text.replace(
+    /"https:\/\/npm\.pkg\.github\.com\/download\/@goodpatch\/([a-z0-9._-]+)\/([^/"]+)\/[0-9a-f]+"/g,
+    (_, name, version) => {
+      count += 1;
+      return `"${registry}@goodpatch/${name}/-/@goodpatch/${name}-${version}.tgz"`;
+    }
+  );
+  return { text: next, count };
+}
+
+/**
+ * lockfile / package.json に出てくる @goodpatch パッケージ名。
+ * AR の tarball URL の末尾（`/-/@goodpatch/<name>-<version>.tgz`）はファイル名なので数えない
+ * （移行済みの lockfile で再実行したときに、別パッケージと誤認して止まらないように）。
+ */
+export function collectGoodpatchPackages(texts) {
+  const names = new Set();
+  for (const text of texts) {
+    for (const match of text.matchAll(/(?<!\/-\/)@goodpatch\/([a-z0-9._-]+)/g)) {
+      names.add(`@goodpatch/${match[1]}`);
+    }
+  }
+  return names;
+}
+
+/**
+ * CI / デプロイ設定で GitHub Packages を前提にしている箇所を探す（書き換えない）。
+ * en: Find CI / deploy settings that assume GitHub Packages. Report only.
+ */
+export function scanCiSettings(root, readDir = fs.readdirSync, readFile = fs.readFileSync) {
+  const findings = [];
+  const workflowsDir = path.join(root, '.github', 'workflows');
+  let workflowFiles = [];
+  try {
+    workflowFiles = readDir(workflowsDir).filter((f) => /\.ya?ml$/.test(f));
+  } catch {
+    // ワークフローが無いプロジェクト
+  }
+  for (const file of workflowFiles.sort()) {
+    const rel = path.join('.github', 'workflows', file);
+    const lines = String(readFile(path.join(workflowsDir, file), 'utf8')).split(/\r?\n/);
+    lines.forEach((line, index) => {
+      if (/npm\.pkg\.github\.com|NODE_AUTH_TOKEN|packages:\s*read/.test(line)) {
+        findings.push({ kind: 'github-actions', file: rel, line: index + 1, text: line.trim() });
+      }
+    });
+  }
+  for (const file of ['vercel.json']) {
+    try {
+      readFile(path.join(root, file), 'utf8');
+      findings.push({ kind: 'vercel', file, line: null, text: null });
+    } catch {
+      // 無ければ対象外
+    }
+  }
+  for (const file of ['.yarnrc.yml', 'yarn.lock']) {
+    try {
+      const text = String(readFile(path.join(root, file), 'utf8'));
+      if (text.includes(GITHUB_REGISTRY_HOST)) {
+        findings.push({ kind: 'yarn', file, line: null, text: null });
+      }
+    } catch {
+      // 無ければ対象外
+    }
+  }
+  return findings;
+}
+
+function readIfExists(file) {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 案内に出す `npx` の指定。auth / migrate-registry を持たない版（2.4.x 以前）は未知のコマンドを
+ * exit 0 で受け流すため、CI に書いた認証が黙って素通りし install が 401 になる。
+ * 実行中の CLI が prerelease なら同じチャネルを付けて、確実にこのコマンドを持つ版を指す。
+ * en: Older releases exit 0 on unknown commands, so point CI at the channel of the running CLI.
+ */
+export function cliSpecForVersion(version) {
+  const channel = /^\d+\.\d+\.\d+-(beta|rc)\.\d+$/.exec(String(version))?.[1];
+  if (channel === 'beta') return 'sparkle-design-cli@beta';
+  if (channel === 'rc') return 'sparkle-design-cli@next';
+  return 'sparkle-design-cli';
+}
+
+function ownVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+  } catch {
+    return null;
+  }
+}
+
+export const defaultDeps = {
+  cwd: () => process.cwd(),
+  log: (...args) => console.log(...args),
+  version: ownVersion,
+};
+
+/**
+ * `migrate-registry` 本体。既定は dry-run（`write: true` のときだけ書き込む）。
+ */
+export async function runMigrateRegistry(options = {}, deps = {}) {
+  const d = { ...defaultDeps, ...deps };
+  const root = path.resolve(d.cwd());
+  const registry = normalizeRegistry(options.registry ?? DEFAULT_REGISTRY);
+  const write = Boolean(options.write);
+
+  if (!fs.existsSync(path.join(root, 'package.json'))) {
+    throw new MigrateRegistryError(
+      `package.json が見つかりません: ${root}\n   プロジェクトのルート（package.json と .npmrc がある場所）で実行してください。`
+    );
+  }
+
+  const files = {
+    npmrc: path.join(root, '.npmrc'),
+    pnpmLock: path.join(root, 'pnpm-lock.yaml'),
+    packageLock: path.join(root, 'package-lock.json'),
+  };
+  const current = {
+    npmrc: readIfExists(files.npmrc) ?? '',
+    pnpmLock: readIfExists(files.pnpmLock),
+    packageLock: readIfExists(files.packageLock),
+    packageJson: readIfExists(path.join(root, 'package.json')),
+  };
+
+  // スコープごと AR に向けるので、AR に無い @goodpatch パッケージがあると引けなくなる
+  const others = [
+    ...collectGoodpatchPackages(
+      [current.packageJson, current.pnpmLock, current.packageLock].filter(Boolean)
+    ),
+  ].filter((name) => !MIGRATABLE_PACKAGES.has(name));
+  if (others.length > 0 && !options.force) {
+    throw new MigrateRegistryError(
+      `Artifact Registry に無い @goodpatch パッケージを使っています: ${others.join(', ')}\n` +
+        `   ${SCOPE} のスコープごと切り替えると、これらが取得できなくなります。\n` +
+        '   AR への移植を Sparkle Design チームに相談するか、影響を承知のうえで --force を付けてください。'
+    );
+  }
+
+  const planned = [];
+  const warnings = [];
+
+  const npmrc = rewriteNpmrc(current.npmrc, registry);
+  warnings.push(...npmrc.warnings);
+  if (npmrc.changes.length > 0) {
+    planned.push({ file: '.npmrc', path: files.npmrc, text: npmrc.text, notes: npmrc.changes });
+  }
+
+  if (current.pnpmLock !== null) {
+    const result = rewritePnpmLock(current.pnpmLock);
+    if (result.count > 0) {
+      planned.push({
+        file: 'pnpm-lock.yaml',
+        path: files.pnpmLock,
+        text: result.text,
+        notes: [`GitHub Packages の tarball URL を ${result.count} 件外す（integrity は残す）`],
+      });
+    }
+    if (result.text.includes(GITHUB_REGISTRY_HOST)) {
+      warnings.push(
+        'pnpm-lock.yaml に GitHub Packages の URL が残っています。手で確認してください'
+      );
+    }
+  }
+
+  if (current.packageLock !== null) {
+    const result = rewritePackageLock(current.packageLock, registry);
+    if (result.count > 0) {
+      planned.push({
+        file: 'package-lock.json',
+        path: files.packageLock,
+        text: result.text,
+        notes: [`resolved を Artifact Registry の URL に ${result.count} 件置き換える`],
+      });
+    }
+    if (result.text.includes(GITHUB_REGISTRY_HOST)) {
+      warnings.push(
+        'package-lock.json に GitHub Packages の URL が残っています。手で確認してください'
+      );
+    }
+  }
+
+  const findings = scanCiSettings(root);
+
+  if (write) {
+    for (const item of planned) fs.writeFileSync(item.path, item.text);
+  }
+
+  const cli = cliSpecForVersion(d.version());
+  report(d.log, { root, registry, write, planned, warnings, findings, cli });
+  return { registry, write, planned, warnings, findings };
+}
+
+function report(log, { registry, write, planned, warnings, findings, cli }) {
+  log(`${write ? '✅' : '🔍'} migrate-registry（${write ? '書き換え' : 'dry-run'}）`);
+  log(`   移行先: ${registry}`);
+  log('');
+  if (planned.length === 0) {
+    log('書き換えるファイルはありません（移行済みか、対象がありません）。');
+  } else {
+    log(write ? '書き換えたファイル:' : '書き換えるファイル（--write で反映）:');
+    for (const item of planned) {
+      log(`  ${item.file}`);
+      for (const note of item.notes) log(`    - ${note}`);
+    }
+  }
+
+  if (warnings.length > 0) {
+    log('');
+    log('⚠️  注意:');
+    for (const warning of warnings) log(`  - ${warning}`);
+  }
+
+  const actions = findings.filter((f) => f.kind === 'github-actions');
+  const vercel = findings.some((f) => f.kind === 'vercel');
+  const yarn = findings.filter((f) => f.kind === 'yarn');
+
+  if (actions.length > 0 || vercel || yarn.length > 0) {
+    log('');
+    log('手で直す必要がある設定（このコマンドは書き換えません）:');
+  }
+  if (actions.length > 0) {
+    log('');
+    log('  [GitHub Actions] GitHub Packages を前提にしている箇所:');
+    for (const f of actions) log(`    ${f.file}:${f.line}  ${f.text}`);
+    log('    → 次の形に置き換えてください:');
+    log('      permissions:');
+    log('        id-token: write   # packages: read は不要');
+    log('        contents: read');
+    log('      ...');
+    log('      - uses: actions/setup-node@v4   # registry-url は外す');
+    log(`      - run: npx --yes ${cli} auth --ci   # 数分で失効するので install の直前に置く`);
+    log('      - run: pnpm install --frozen-lockfile   # NODE_AUTH_TOKEN は不要');
+  }
+  if (vercel) {
+    log('');
+    log('  [Vercel] vercel.json があります。Vercel でビルドしているなら:');
+    log('    1. Settings → Security で OIDC federation を有効にし、Issuer Mode を Team にする');
+    log('    2. Install Command を次にする:');
+    log(`       npx --yes ${cli} auth --ci && pnpm install --frozen-lockfile`);
+    log('    3. GitHub Packages 用の環境変数（NODE_AUTH_TOKEN など）を削除する');
+  }
+  for (const f of yarn) {
+    log('');
+    log(
+      `  [yarn] ${f.file} に GitHub Packages の設定があります。yarn は自動書き換えの対象外です。`
+    );
+  }
+
+  log('');
+  log('次にやること:');
+  if (!write) log('  0. 内容を確認して --write を付けて再実行する');
+  log(`  1. npx --yes ${cli} auth   # ローカルの認証（約 60 分で失効）`);
+  log('  2. pnpm install --frozen-lockfile   # Artifact Registry から取得できることを確認');
+}

package/package.json

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