github-settings-as-code 1.2.10 → 2.0.1

package/src/github/actions-settings/constants.mts

@@ -0,0 +1,50 @@
+import * as t from 'ts-fortress';
+
+/**
+ * `github/actions-settings/settings.json` の型。
+ *
+ * Settings > Actions > General に対応する。 2 つの API をまとめて 1 ファイルで
+ * 管理する:
+ *
+ * - `GET|PUT /repos/{owner}/{repo}/actions/permissions`
+ * - `GET|PUT /repos/{owner}/{repo}/actions/permissions/fork-pr-contributor-approval`
+ */
+export const ActionsSettings = t.record({
+  /** Actions permissions: この repository で Actions を有効にするか。 */
+  enabled: t.boolean(true),
+
+  /** Actions permissions: 実行を許可する action の範囲。 */
+  allowed_actions: t.enumType(['all', 'local_only', 'selected'], {
+    typeName: 'AllowedActions',
+    defaultValue: 'all',
+  }),
+
+  /**
+   * 「 Require actions to be pinned to a full-length commit SHA 」。
+   *
+   * NOTE: @octokit/types v16 時点でこのフィールドは型定義に入っていないため、
+   * リクエスト時にのみ手当てしている（ set-actions-permissions.mts 参照）。
+   */
+  sha_pinning_required: t.boolean(false),
+
+  /**
+   * 「 Approval for running fork pull request workflows from contributors 」。
+   *
+   * - `first_time_contributors_new_to_github`: GitHub 自体に不慣れな初回貢献者のみ承認必須
+   * - `first_time_contributors`: この repository への初回貢献者のみ承認必須
+   * - `all_external_contributors`: 外部貢献者すべてに承認必須
+   */
+  fork_pr_contributor_approval_policy: t.enumType(
+    [
+      'first_time_contributors_new_to_github',
+      'first_time_contributors',
+      'all_external_contributors',
+    ],
+    {
+      typeName: 'ForkPrContributorApprovalPolicy',
+      defaultValue: 'all_external_contributors',
+    },
+  ),
+});
+
+export type ActionsSettings = t.TypeOf<typeof ActionsSettings>;

package/src/github/actions-settings/index.mts

@@ -0,0 +1,4 @@
+export * from './api/index.mjs';
+export * from './apply.mjs';
+export * from './backup.mjs';
+export * from './constants.mjs';

package/src/github/constants.mts

@@ -1,57 +1,24 @@
-import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
-import { hasKey, isRecord, isString, Json } from 'ts-data-forge';
-import { Result } from 'ts-repo-utils';
+import { resolveTargetRepo } from './resolve-target-repo.mjs';
 
-const ownerNullable = process.env['OWNER'];
+const targetRepo = await resolveTargetRepo();
 
-if (ownerNullable === undefined) {
-  throw new Error('OWNER env var is not set');
-}
+export const OWNER: string = targetRepo.owner;
 
-export const OWNER = ownerNullable;
-
-const getRepoName = async (): Promise<string> => {
-  const repoNameEnv = process.env['REPO_NAME'];
-
-  if (repoNameEnv !== undefined) {
-    return repoNameEnv;
-  }
-
-  const packageJsonPath = path.resolve(process.cwd(), './package.json');
-
-  // eslint-disable-next-line security/detect-non-literal-fs-filename
-  const packageJsonStr = await fs.readFile(packageJsonPath, {
-    encoding: 'utf8',
-  });
-
-  const packageJson = Json.parse(packageJsonStr);
-
-  if (Result.isErr(packageJson)) {
-    throw new Error(packageJson.value);
-  }
-
-  if (
-    !isRecord(packageJson.value) ||
-    !hasKey(packageJson.value, 'name') ||
-    !isString(packageJson.value.name)
-  ) {
-    throw new Error('package.json not parsed correctly');
-  }
-
-  return packageJson.value.name;
-};
-
-export const REPO: string = await getRepoName();
+export const REPO: string = targetRepo.repo;
 
 const githubDir = path.resolve(process.cwd(), './github');
 
+export const settingsJsonName = 'settings.json';
+
 export const repositorySettingsDir = path.resolve(
   githubDir,
   './repository-settings',
 );
 
-export const repositorySettingsJsonName = 'settings.json';
+export const actionsSettingsDir = path.resolve(githubDir, './actions-settings');
+
+export const pagesSettingsDir = path.resolve(githubDir, './pages');
 
 export const rulesetsDir = path.resolve(githubDir, './rulesets');
 

package/src/github/index.mts

@@ -1,4 +1,8 @@
+export * from './actions-settings/index.mjs';
 export * from './constants.mjs';
+export * from './pages/index.mjs';
 export * from './repository/index.mjs';
+export * from './resolve-target-repo.mjs';
 export * from './ruleset/index.mjs';
+export * from './upgrade-stale-codec.mjs';
 export * from './variables/index.mjs';

package/src/github/octokit.mts

@@ -1,5 +1,49 @@
 import { Octokit } from '@octokit/core';
+import { execFileSync } from 'node:child_process';
 
-export const octokit = new Octokit({
-  auth: process.env['PERSONAL_ACCESS_TOKEN'],
-});
+/**
+ * GitHub API の認証トークンを解決する。
+ *
+ * 1. 明示的な環境変数 … CI では GitHub App の installation token を渡す。
+ * 2. `gh auth token` … ローカルでは gh CLI のログイン情報をそのまま使うため、 PAT
+ *    を .env などに平文で置く必要がない。
+ *
+ * `GITHUB_TOKEN` は候補に含めない。 Actions では既定の（ administration 権限を
+ * 持たない）トークンが同名で入っていることがあり、黙って弱い方を掴むため。
+ */
+const resolveAuthToken = (): string => {
+  const fromEnv =
+    process.env['GITHUB_APP_TOKEN'] ??
+    process.env['GH_TOKEN'] ??
+    process.env['PERSONAL_ACCESS_TOKEN'];
+
+  if (fromEnv !== undefined && fromEnv !== '') {
+    return fromEnv;
+  }
+
+  try {
+    // シェルを経由させない。 stderr も捨てて、失敗時にトークンが混ざらないようにする。
+    const stdout = execFileSync('gh', ['auth', 'token'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+
+    const token = stdout.trim();
+
+    if (token.length > 0) {
+      return token;
+    }
+  } catch {
+    // gh が未インストール、または未ログイン。下のエラーにまとめる。
+  }
+
+  throw new Error(
+    [
+      'GitHub のトークンが見つかりませんでした。',
+      'CI では GH_TOKEN（ GitHub App の installation token ）を設定してください。',
+      'ローカルでは `gh auth login` を実行すれば、その認証がそのまま使われます。',
+    ].join('\n'),
+  );
+};
+
+export const octokit = new Octokit({ auth: resolveAuthToken() });

package/src/github/pages/api/get-pages-settings.mts

@@ -0,0 +1,35 @@
+import { type EndpointKeys } from 'octokit-safe-types';
+import { octokitHeaders, OWNER, REPO } from '../../constants.mjs';
+import { octokit } from '../../octokit.mjs';
+import { PagesSettings } from '../constants.mjs';
+
+/**
+ * GitHub Pages の現在の設定を取得する。
+ *
+ * Pages が未設定の repository では 404 が返るため、その場合は `undefined` を返す。
+ */
+export const getPagesSettings = async (): Promise<
+  PagesSettings | undefined
+> => {
+  try {
+    // https://docs.github.com/rest/pages/pages#get-a-apiname-pages-site
+    const response = await octokit.request(
+      'GET /repos/{owner}/{repo}/pages' satisfies EndpointKeys,
+      { owner: OWNER, repo: REPO, headers: octokitHeaders },
+    );
+
+    // eslint-disable-next-line unicorn/no-array-fill-with-reference-type
+    return PagesSettings.fill({ build_type: response.data.build_type });
+  } catch (error) {
+    if (
+      typeof error === 'object' &&
+      error !== null &&
+      Object.hasOwn(error, 'status') &&
+      (error as Readonly<{ status?: unknown }>).status === 404
+    ) {
+      return undefined;
+    }
+
+    throw error;
+  }
+};

package/src/github/pages/api/index.mts

@@ -0,0 +1,2 @@
+export * from './get-pages-settings.mjs';
+export * from './set-pages-settings.mjs';

package/src/github/pages/api/set-pages-settings.mts

@@ -0,0 +1,47 @@
+import { type EndpointKeys } from 'octokit-safe-types';
+import { octokitHeaders, OWNER, REPO } from '../../constants.mjs';
+import { octokit } from '../../octokit.mjs';
+import { type PagesSettings } from '../constants.mjs';
+import { getPagesSettings } from './get-pages-settings.mjs';
+
+/**
+ * GitHub Pages の Source を JSON の内容に合わせる。
+ *
+ * Pages 未設定なら POST で作成し、設定済みなら PUT で更新する。 これにより
+ * 「 Settings > Pages で Source を GitHub Actions に変更する 」という手作業が不要になる。
+ */
+export const setPagesSettings = async (
+  settings: PagesSettings,
+): Promise<void> => {
+  const current = await getPagesSettings();
+
+  if (current === undefined) {
+    // https://docs.github.com/rest/pages/pages#create-a-apiname-pages-site
+    await octokit.request(
+      'POST /repos/{owner}/{repo}/pages' satisfies EndpointKeys,
+      {
+        owner: OWNER,
+        repo: REPO,
+        headers: octokitHeaders,
+        build_type: settings.build_type,
+      },
+    );
+
+    return;
+  }
+
+  if (current.build_type === settings.build_type) {
+    return;
+  }
+
+  // https://docs.github.com/rest/pages/pages#update-information-about-a-apiname-pages-site
+  await octokit.request(
+    'PUT /repos/{owner}/{repo}/pages' satisfies EndpointKeys,
+    {
+      owner: OWNER,
+      repo: REPO,
+      headers: octokitHeaders,
+      build_type: settings.build_type,
+    },
+  );
+};

package/src/github/pages/apply.mts

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import 'dotenv/config';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { validationErrorsToMessages } from 'ts-fortress';
+import {
+  formatUncommittedFiles,
+  isDirectlyExecuted,
+  pathExists,
+  Result,
+} from 'ts-repo-utils';
+import { pagesSettingsDir, settingsJsonName } from '../constants.mjs';
+import { getPagesSettings, setPagesSettings } from './api/index.mjs';
+import { PagesSettings } from './constants.mjs';
+
+/**
+ * `github/pages/settings.json` を Settings > Pages に反映する。
+ *
+ * 設定ファイルを置いていない repository では何もしない（ Pages を使わない
+ * repository で誤って Pages を有効化しないため）。
+ */
+export const applyPagesSettings = async (): Promise<void> => {
+  const settingsPath = path.resolve(pagesSettingsDir, settingsJsonName);
+
+  if (!(await pathExists(settingsPath))) {
+    return;
+  }
+
+  const settings = await readSettings(settingsPath);
+
+  await setPagesSettings(settings);
+
+  // 反映後の実際の値でローカルのファイルを更新する
+  {
+    const applied = await getPagesSettings();
+
+    if (applied === undefined) {
+      return;
+    }
+
+    const str = JSON.stringify(applied, undefined, 2);
+
+    // eslint-disable-next-line security/detect-non-literal-fs-filename
+    await fs.writeFile(settingsPath, str);
+
+    // eslint-disable-next-line security/detect-non-literal-fs-filename
+    await fs.writeFile(
+      path.resolve(pagesSettingsDir, 'bk', settingsJsonName),
+      str,
+    );
+
+    await formatUncommittedFiles();
+  }
+};
+
+const readSettings = async (settingsPath: string): Promise<PagesSettings> => {
+  // eslint-disable-next-line security/detect-non-literal-fs-filename
+  const settingsText = await fs.readFile(settingsPath, { encoding: 'utf8' });
+
+  const validationResult = PagesSettings.validate(JSON.parse(settingsText));
+
+  if (Result.isErr(validationResult)) {
+    throw new Error(
+      validationErrorsToMessages(validationResult.value).join('\n'),
+    );
+  }
+
+  return validationResult.value;
+};
+
+if (isDirectlyExecuted(import.meta.url)) {
+  await applyPagesSettings();
+}

package/src/github/pages/backup.mts

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import 'dotenv/config';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import {
+  formatUncommittedFiles,
+  isDirectlyExecuted,
+  makeEmptyDir,
+} from 'ts-repo-utils';
+import { pagesSettingsDir, settingsJsonName } from '../constants.mjs';
+import { getPagesSettings } from './api/index.mjs';
+
+const backupDir = path.resolve(pagesSettingsDir, './bk');
+
+/** Settings > Pages の現在値を `bk/` に保存する。 */
+export const backupPagesSettings = async (
+  fmt: boolean = true,
+): Promise<void> => {
+  await makeEmptyDir(backupDir);
+
+  const settings = await getPagesSettings();
+
+  if (settings === undefined) {
+    console.warn(
+      'GitHub Pages is not enabled for this repository; skipping backup.',
+    );
+
+    return;
+  }
+
+  // eslint-disable-next-line security/detect-non-literal-fs-filename
+  await fs.writeFile(
+    path.resolve(backupDir, settingsJsonName),
+    JSON.stringify(settings, undefined, 2),
+  );
+
+  if (fmt) {
+    await formatUncommittedFiles();
+  }
+};
+
+if (isDirectlyExecuted(import.meta.url)) {
+  await backupPagesSettings();
+}

package/src/github/pages/constants.mts

@@ -0,0 +1,16 @@
+import * as t from 'ts-fortress';
+
+/**
+ * `github/pages/settings.json` の型。
+ *
+ * Settings > Pages > Build and deployment > Source に対応する。
+ * `workflow` が GUI 上の「 GitHub Actions 」、 `legacy` が「 Deploy from a branch 」。
+ */
+export const PagesSettings = t.record({
+  build_type: t.enumType(['workflow', 'legacy'], {
+    typeName: 'PagesBuildType',
+    defaultValue: 'workflow',
+  }),
+});
+
+export type PagesSettings = t.TypeOf<typeof PagesSettings>;

package/src/github/pages/index.mts

@@ -0,0 +1,4 @@
+export * from './api/index.mjs';
+export * from './apply.mjs';
+export * from './backup.mjs';
+export * from './constants.mjs';

package/src/github/repository/apply.mts

@@ -10,10 +10,7 @@ import {
   isDirectlyExecuted,
   Result,
 } from 'ts-repo-utils';
-import {
-  repositorySettingsDir,
-  repositorySettingsJsonName,
-} from '../constants.mjs';
+import { repositorySettingsDir, settingsJsonName } from '../constants.mjs';
 import { getRepositorySettings, updateRepository } from './api/index.mjs';
 import { backupRepositorySettings } from './backup.mjs';
 import {
@@ -70,13 +67,13 @@ export const applyRepositorySettings = async (): Promise<void> => {
 
     // eslint-disable-next-line security/detect-non-literal-fs-filename
     await fs.writeFile(
-      path.resolve(repositorySettingsDir, repositorySettingsJsonName),
+      path.resolve(repositorySettingsDir, settingsJsonName),
       str,
     );
 
     // eslint-disable-next-line security/detect-non-literal-fs-filename
     await fs.writeFile(
-      path.resolve(repositorySettingsDir, 'bk', repositorySettingsJsonName),
+      path.resolve(repositorySettingsDir, 'bk', settingsJsonName),
       str,
     );
 
@@ -87,7 +84,7 @@ export const applyRepositorySettings = async (): Promise<void> => {
 const readSettings = async (): Promise<RepositoryPicked> => {
   // eslint-disable-next-line security/detect-non-literal-fs-filename
   const settingsText = await fs.readFile(
-    path.resolve(repositorySettingsDir, repositorySettingsJsonName),
+    path.resolve(repositorySettingsDir, settingsJsonName),
     {
       encoding: 'utf8',
     },

package/src/github/repository/backup.mts

@@ -8,10 +8,7 @@ import {
   isDirectlyExecuted,
   makeEmptyDir,
 } from 'ts-repo-utils';
-import {
-  repositorySettingsDir,
-  repositorySettingsJsonName,
-} from '../constants.mjs';
+import { repositorySettingsDir, settingsJsonName } from '../constants.mjs';
 import { getRepositorySettings } from './api/index.mjs';
 import { repositoryKeysToPick } from './constants.mjs';
 
@@ -26,7 +23,7 @@ export const backupRepositorySettings = async (
 
   // eslint-disable-next-line security/detect-non-literal-fs-filename
   await fs.writeFile(
-    path.resolve(backupDir, repositorySettingsJsonName),
+    path.resolve(backupDir, settingsJsonName),
     JSON.stringify(
       Obj.pick(repositorySettings, repositoryKeysToPick),
       undefined,

package/src/github/repository/constants.mts

@@ -5,6 +5,7 @@ import {
 import { expectType } from 'ts-data-forge';
 import * as t from 'ts-fortress';
 import { type StrictExclude } from 'ts-type-forge';
+import { upgradeStaleCodec } from '../upgrade-stale-codec.mjs';
 
 const keysToPickBase = [
   'allow_auto_merge',
@@ -63,6 +64,9 @@ export type RepositoryKeysToPick = StrictExclude<
 
 expectType<keyof UpdateRepositoryRequest, RepositoryKeysToPick>('>=');
 
-export const RepositoryPicked = t.pick(FullRepository, repositoryKeysToPick);
+export const RepositoryPicked = t.pick(
+  upgradeStaleCodec(FullRepository),
+  repositoryKeysToPick,
+);
 
 export type RepositoryPicked = t.TypeOf<typeof RepositoryPicked>;

package/src/github/resolve-target-repo.mts

@@ -0,0 +1,144 @@
+import { execFileSync } from 'node:child_process';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as util from 'node:util';
+import { hasKey, isRecord, isString, Json } from 'ts-data-forge';
+import { Result } from 'ts-repo-utils';
+
+export type TargetRepo = Readonly<{
+  owner: string;
+  repo: string;
+}>;
+
+/** `strict: false` の解析結果は string | boolean | 配列 になりうるため絞り込む。 */
+const pickString = (value: unknown): string | undefined =>
+  isString(value) && value !== '' ? value : undefined;
+
+/**
+ * コマンドライン引数から `--owner` / `--repo` を読む。
+ *
+ * サブコマンドや他のフラグと共存できるよう `strict: false` で解析する。
+ */
+const fromCliArgs = (): Partial<TargetRepo> => {
+  const { values } = util.parseArgs({
+    args: process.argv.slice(2),
+    options: {
+      owner: { type: 'string' },
+      repo: { type: 'string' },
+    },
+    strict: false,
+    allowPositionals: true,
+  });
+
+  return {
+    owner: pickString(values.owner),
+    repo: pickString(values.repo),
+  };
+};
+
+const fromEnv = (): Partial<TargetRepo> =>
+  ({
+    owner: process.env['OWNER'],
+    repo: process.env['REPO_NAME'],
+  }) as const;
+
+/**
+ * `git remote get-url origin` から owner / repo を推測する。
+ *
+ * SSH 形式（ `git@github.com:owner/repo.git` ）と HTTPS 形式
+ * （ `https://github.com/owner/repo.git` ）の両方に対応する。
+ */
+const fromGitRemote = (): Partial<TargetRepo> => {
+  try {
+    const url = execFileSync('git', ['remote', 'get-url', 'origin'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+
+    const matched =
+      /^(?:git@[^:]+:|(?:https?|ssh):\/\/[^/]+\/)(?<owner>[^/]+)\/(?<repo>[^/]+?)(?:\.git)?$/u.exec(
+        url,
+      );
+
+    return {
+      owner: matched?.groups?.['owner'],
+      repo: matched?.groups?.['repo'],
+    };
+  } catch {
+    return {};
+  }
+};
+
+/** `package.json` の `name` を repository 名として使う（最後の手段）。 */
+const fromPackageJson = async (): Promise<Partial<TargetRepo>> => {
+  const packageJsonPath = path.resolve(process.cwd(), './package.json');
+
+  try {
+    // eslint-disable-next-line security/detect-non-literal-fs-filename
+    const packageJsonStr = await fs.readFile(packageJsonPath, {
+      encoding: 'utf8',
+    });
+
+    const packageJson = Json.parse(packageJsonStr);
+
+    if (
+      Result.isErr(packageJson) ||
+      !isRecord(packageJson.value) ||
+      !hasKey(packageJson.value, 'name') ||
+      !isString(packageJson.value.name)
+    ) {
+      return {};
+    }
+
+    return { repo: packageJson.value.name };
+  } catch {
+    return {};
+  }
+};
+
+/**
+ * 操作対象の repository を決める。
+ *
+ * 優先順位は以下の通り。
+ *
+ * 1. コマンドライン引数 `--owner` / `--repo`
+ * 2. 環境変数 `OWNER` / `REPO_NAME`
+ * 3. `git remote get-url origin`
+ * 4. `package.json` の `name` （ repo のみ ）
+ */
+export const resolveTargetRepo = async (): Promise<TargetRepo> => {
+  const sources: readonly Partial<TargetRepo>[] = [
+    fromCliArgs(),
+    fromEnv(),
+    fromGitRemote(),
+    await fromPackageJson(),
+  ] as const;
+
+  const owner = sources.map((s) => s.owner).find((v) => v !== undefined);
+
+  if (owner === undefined) {
+    throw new Error(
+      [
+        'owner を特定できませんでした。次のいずれかで指定してください:',
+        '  --owner <owner> （コマンドライン引数）',
+        '  OWNER=<owner>   （環境変数）',
+        '  git remote add origin <URL> （ origin の URL から推測されます）',
+      ].join('\n'),
+    );
+  }
+
+  const repo = sources.map((s) => s.repo).find((v) => v !== undefined);
+
+  if (repo === undefined) {
+    throw new Error(
+      [
+        'repository 名を特定できませんでした。次のいずれかで指定してください:',
+        '  --repo <repo>     （コマンドライン引数）',
+        '  REPO_NAME=<repo>  （環境変数）',
+        '  git remote add origin <URL> （ origin の URL から推測されます）',
+      ].join('\n'),
+    );
+  }
+
+  return { owner, repo };
+};

package/src/github/ruleset/api/get-all-rulesets.mts

@@ -35,18 +35,15 @@ export const getAllRulesets = async (): Promise<GetAllRulesetsResponse> => {
           enforcement: components['schemas']['repository-rule-enforcement'];
           bypass_actors?: components['schemas']['repository-ruleset-bypass-actor'][];
           current_user_can_bypass?:
-            | 'always'
-            | 'pull_requests_only'
-            | 'never'
-            | 'exempt';
+            'always' | 'pull_requests_only' | 'never' | 'exempt';
           node_id?: string;
           _links?: {
             self?: {
               href?: string;
             };
-            html?: {
+            html?: null | {
               href?: string;
-            } | null;
+            };
           };
           conditions?:
             | (

package/src/github/ruleset/constants.mts

@@ -5,6 +5,7 @@ import {
 } from 'octokit-safe-types';
 import { expectType } from 'ts-data-forge';
 import * as t from 'ts-fortress';
+import { upgradeStaleCodec } from '../upgrade-stale-codec.mjs';
 
 export const rulesetKeysToPick = [
   'id',
@@ -22,6 +23,9 @@ expectType<keyof UpdateRulesetRequest | 'id', KeysToPick>('=');
 
 expectType<keyof CreateRulesetRequest, keyof UpdateRulesetRequest>('=');
 
-export const RulesetPicked = t.pick(RepositoryRuleset, rulesetKeysToPick);
+export const RulesetPicked = t.pick(
+  upgradeStaleCodec(RepositoryRuleset),
+  rulesetKeysToPick,
+);
 
 export type RulesetPicked = t.TypeOf<typeof RulesetPicked>;