@ebalzan/ci 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ebalzan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/cli.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+//
+// ebalzan-ci — the command-line entry point of @ebalzan/ci.
+//
+// sync is lib/sync.mjs, onboard lib/onboard.mjs. `ebalzan-ci <cmd> --help`
+// prints the command's own help.
+
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+
+import { onboard } from '../lib/onboard.mjs'
+import { sync } from '../lib/sync.mjs'
+
+const BIN_DIR = dirname(fileURLToPath(import.meta.url))
+const ROOT = dirname(BIN_DIR)
+const COMMITLINT_CONFIG = join(ROOT, 'commitlint.config.mjs')
+
+const HELP = `Usage: ebalzan-ci <command> [options]
+
+Commands:
+  sync           Push variables, secrets, settings and rulesets to this repo
+  onboard        Add the shared workflows, hook and rules to a repo, then sync it
+  commit-msg     Validate a commit message (the husky commit-msg hook calls this)
+  version        Print the package version
+  help           Show this help
+
+Run 'ebalzan-ci <command> --help' for a command's options.`
+
+function version() {
+  return JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8')).version
+}
+
+// commit-msg FILE|SUBJECT — husky passes the path of the message file; a
+// non-path argument is checked as the subject itself (handy for scripts). The
+// subject goes through commitlint with commitlint.config.mjs — the rule the
+// work-PR check applies to the PR title and commits. Subjects git writes itself
+// (Merge …, Revert "…", fixup! …) are let through by commitlint's defaults.
+function commitMsg(args) {
+  const [arg] = args
+  if (!arg || arg === '--help' || arg === '-h') {
+    console.log('Usage: ebalzan-ci commit-msg <message-file | subject>')
+    return arg ? 0 : 1
+  }
+  const text = existsSync(arg) ? readFileSync(arg, 'utf8') : arg
+  const subject =
+    text
+      .split(/\r?\n/)
+      .find(line => line.trim() && !line.startsWith('#'))
+      ?.trim() ?? ''
+  const result = spawnSync(process.execPath, [commitlintCli(), '--config', COMMITLINT_CONFIG], {
+    input: `${subject}\n`,
+    stdio: ['pipe', 'inherit', 'inherit'],
+  })
+  if (result.error) {
+    console.error(`ebalzan-ci: could not run commitlint: ${result.error.message}`)
+    return 127
+  }
+  if (result.status === 0) return 0
+  console.log(`Invalid commit message: "${subject}"`)
+  console.log('Use Conventional Commits, for example:')
+  console.log('  feat(viewer): add section filters')
+  console.log('  fix: prevent null model crash')
+  return 1
+}
+
+function commitlintCli() {
+  const require = createRequire(import.meta.url)
+  return join(dirname(require.resolve('@commitlint/cli/package.json')), 'cli.js')
+}
+
+async function main(argv) {
+  const [command, ...args] = argv
+  switch (command) {
+    case 'sync':
+      return sync(args)
+    case 'onboard':
+      return onboard(args)
+    case 'commit-msg':
+      return commitMsg(args)
+    case 'version':
+    case '--version':
+    case '-v':
+      console.log(version())
+      return 0
+    case undefined:
+    case 'help':
+    case '--help':
+    case '-h':
+      console.log(HELP)
+      return command === undefined ? 1 : 0
+    default:
+      console.error(`ebalzan-ci: unknown command '${command}'.\n\n${HELP}`)
+      return 1
+  }
+}
+
+process.exit(await main(process.argv.slice(2)))

package/commitlint.config.mjs

@@ -0,0 +1,39 @@
+// The one Conventional Commits rule (commitlint), used by the husky commit-msg
+// hook (`ebalzan-ci commit-msg`) and by the PR check on the PR title and
+// every commit of the PR (actions/pr-checks). The types come from
+// config/types.json.
+//
+// Deliberately no @commitlint/config-conventional: only the header shape is
+// enforced — `<type>(<scope>)!: <subject>`, scope and `!` optional — as the
+// release PR's version and title read it (config/cliff.toml, scripts/release-title.mjs). Git's own subjects
+// (Merge …, Revert "…", fixup! …) are ignored by commitlint's defaults.
+
+import { readFileSync } from 'node:fs'
+
+import { stripDocKeys } from './lib/config.mjs'
+
+// { <type>: { release, color } }, in config/types.json's order (precedence).
+export const TYPES = stripDocKeys(
+  JSON.parse(readFileSync(new URL('./config/types.json', import.meta.url), 'utf8')),
+)
+export const types = Object.keys(TYPES)
+
+// THE Conventional Commit header: commitlint parses with it, and the PR rules
+// (actions/pr-checks) and the release title (scripts/release-title.mjs) read the
+// type and the `!` with it. Not anchored at the end: it also runs on whole
+// multi-line commit messages.
+export const HEADER_PATTERN = /^(?<type>\w*)(?:\((?<scope>[^)]+)\))?(?<breaking>!)?: (?<subject>.+)/
+
+export default {
+  parserPreset: {
+    parserOpts: {
+      headerPattern: HEADER_PATTERN,
+      headerCorrespondence: ['type', 'scope', 'breaking', 'subject'],
+    },
+  },
+  rules: {
+    'type-empty': [2, 'never'],
+    'type-enum': [2, 'always', types],
+    'subject-empty': [2, 'never'],
+  },
+}

package/config/actions.env

@@ -0,0 +1,28 @@
+# SHARED GitHub Actions VARIABLES — the house rules every repo running the
+# CI actions gets. Non-sensitive; committed; published with the package.
+#
+# A repo adds or overrides any key in its own .github/actions.env; the repo's
+# value wins. Keep here only what is genuinely the same everywhere — anything
+# tied to one project (AUTO_PROJECT_NUMBER, AUTO_MILESTONE_TITLE, deploy
+# settings) belongs to that repo.
+#
+# Read at run time, never copied onto repos: the actions load this file from the
+# copy of ebalzan/ci the runner downloads for `uses: …@v1`
+# (scripts/shared-vars.mjs) and fill every key the repo leaves unset. A change
+# here reaches the repos when it is released and the major tag moves to it — no
+# bootstrap run.
+#
+# A key with a default in the code is not repeated here: the board owner is the
+# repo owner, a PR over 500 changed lines gets a warning
+# (AUTO_MAX_CHANGED_LINES), the branches are dev and main
+# (scripts/shared-vars.mjs), and there is no board or milestone unless the repo
+# sets one. The workflows pass the repo's variables whole (REPO_VARS_JSON), so
+# setting a key here or in a repo is all it takes — no workflow edit.
+
+# Claude model that writes the PR descriptions (actions/auto-pr/describe.sh,
+# through Claude Code). Defined only here: without it there is no AI
+# description. AUTO_DESCRIBE_EFFORT: low | medium | high | xhigh | max —
+# ignored for Haiku, which does not accept it; unset leaves Claude Code's
+# default.
+AUTO_DESCRIBE_MODEL=claude-sonnet-5-5
+AUTO_DESCRIBE_EFFORT=low

package/config/repo-settings.json

@@ -0,0 +1,12 @@
+{
+  "$comment": "Repository settings every managed repo gets (PATCH /repos/{owner}/{repo}). A repo overrides any key in its own .github/repo-settings.json. Keys starting with $ are documentation and are never sent. Work PRs are squash-merged into dev (the PR title becomes the commit); the dev → main release PR is merged with a merge commit (GitHub's default title, which commitlint and git-cliff skip). Rebase merges are off: they rewrite commits.",
+  "allow_squash_merge": true,
+  "allow_merge_commit": true,
+  "allow_rebase_merge": false,
+  "squash_merge_commit_title": "PR_TITLE",
+  "squash_merge_commit_message": "COMMIT_MESSAGES",
+  "merge_commit_title": "MERGE_MESSAGE",
+  "merge_commit_message": "PR_TITLE",
+  "delete_branch_on_merge": true,
+  "allow_update_branch": true
+}

package/config/rulesets/protect-dev.json

@@ -0,0 +1,10 @@
+{
+  "$comment": "dev is the integration branch: it cannot be deleted or force-pushed. The Release workflow only fast-forwards it (or merges main into it), so nothing in the pipeline needs a bypass.",
+  "name": "ci: protect dev",
+  "target": "branch",
+  "enforcement": "active",
+  "conditions": {
+    "ref_name": { "include": ["refs/heads/dev"], "exclude": [] }
+  },
+  "rules": [{ "type": "deletion" }, { "type": "non_fast_forward" }]
+}

package/config/rulesets/protect-main.json

@@ -0,0 +1,10 @@
+{
+  "$comment": "main is the release branch: it cannot be deleted or force-pushed. The Release workflow only fast-forwards it with the `chore(release): X.Y.Z` commit, so nothing in the pipeline needs a bypass.",
+  "name": "ci: protect main",
+  "target": "branch",
+  "enforcement": "active",
+  "conditions": {
+    "ref_name": { "include": ["refs/heads/main"], "exclude": [] }
+  },
+  "rules": [{ "type": "deletion" }, { "type": "non_fast_forward" }]
+}

package/config/rulesets/require-pull-request.json

@@ -0,0 +1,33 @@
+{
+  "$comment": "Changes reach dev only through a squash-merged work PR whose 'pr-check / Work PR' check passed — its title becomes the one commit on dev. main is require-release-pr.json's. DISABLED by default: the Release workflow brings dev up to main with GITHUB_TOKEN (a fast-forward, or a merge of main when work landed meanwhile), so the GitHub Actions app (Integration 15368) must be able to bypass it. Enable it per repo with .github/rulesets/require-pull-request.json containing {\"enforcement\": \"active\"}, run one release, and confirm it went through.",
+  "name": "ci: require pull request",
+  "target": "branch",
+  "enforcement": "disabled",
+  "conditions": {
+    "ref_name": { "include": ["refs/heads/dev"], "exclude": [] }
+  },
+  "bypass_actors": [
+    { "actor_id": 5, "actor_type": "RepositoryRole", "bypass_mode": "always" },
+    { "actor_id": 15368, "actor_type": "Integration", "bypass_mode": "always" }
+  ],
+  "rules": [
+    {
+      "type": "pull_request",
+      "parameters": {
+        "required_approving_review_count": 0,
+        "dismiss_stale_reviews_on_push": false,
+        "require_code_owner_review": false,
+        "require_last_push_approval": false,
+        "required_review_thread_resolution": false,
+        "allowed_merge_methods": ["squash"]
+      }
+    },
+    {
+      "type": "required_status_checks",
+      "parameters": {
+        "strict_required_status_checks_policy": false,
+        "required_status_checks": [{ "context": "pr-check / Work PR" }]
+      }
+    }
+  ]
+}

package/config/rulesets/require-release-pr.json

@@ -0,0 +1,33 @@
+{
+  "$comment": "Changes reach main only through the dev → main release PR, merged with a merge commit after 'pr-check / Release PR' passed: dev's commits reach main unchanged, so dev catches up without a force-push. The Release workflow fails on a squash or rebase merge; this ruleset hides those buttons. DISABLED by default: the Release workflow pushes the `chore(release): X.Y.Z` commit to main with GITHUB_TOKEN, so the GitHub Actions app (Integration 15368) must be able to bypass it. Enable it per repo with .github/rulesets/require-release-pr.json containing {\"enforcement\": \"active\"}, run one release, and confirm it went through.",
+  "name": "ci: require release pull request",
+  "target": "branch",
+  "enforcement": "disabled",
+  "conditions": {
+    "ref_name": { "include": ["refs/heads/main"], "exclude": [] }
+  },
+  "bypass_actors": [
+    { "actor_id": 5, "actor_type": "RepositoryRole", "bypass_mode": "always" },
+    { "actor_id": 15368, "actor_type": "Integration", "bypass_mode": "always" }
+  ],
+  "rules": [
+    {
+      "type": "pull_request",
+      "parameters": {
+        "required_approving_review_count": 0,
+        "dismiss_stale_reviews_on_push": false,
+        "require_code_owner_review": false,
+        "require_last_push_approval": false,
+        "required_review_thread_resolution": false,
+        "allowed_merge_methods": ["merge"]
+      }
+    },
+    {
+      "type": "required_status_checks",
+      "parameters": {
+        "strict_required_status_checks_policy": false,
+        "required_status_checks": [{ "context": "pr-check / Release PR" }]
+      }
+    }
+  ]
+}

package/config/secrets.env.example

@@ -0,0 +1,33 @@
+# SHARED repository SECRETS — every repo you run `ebalzan-ci sync` in gets these.
+#
+# 1. Copy:  cp config/secrets.env.example config/secrets.env
+# 2. Fill in the real values (the copy is gitignored).
+# 3. Sync:  run `npx ebalzan-ci sync` in each repo (here: npm run gh:sync)
+#
+# A repo adds or overrides any key in its own .github/secrets.env (the repo's
+# value wins). Shared secrets for a GitHub ENVIRONMENT would go in
+# config/secrets.<environment>.env, overridable by the repo's
+# .github/secrets.<environment>.env — none exist today: every deploy secret is
+# specific to one repo's deploy target.
+#
+# GITHUB_TOKEN is provided automatically by Actions — never set it here.
+
+# Anthropic API key used by auto-pr.yml (Claude Code) to describe work PRs and
+# summarize the release PR.
+# https://console.anthropic.com/settings/keys
+ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxx
+
+# CLASSIC PAT used by auto-pr.yml to write to your user Projects (v2) boards,
+# and so the PRs it opens and edits (work PRs, the release PR) trigger PR
+# Checks; pr-check.yml reads the board with it to check the PR is on it.
+# Scopes: `project` (read/write on Projects v2) and `repo` (create issues/PRs on
+# private repos).
+#
+# It must be classic, not fine-grained: the boards are owned by your personal
+# account, and a fine-grained PAT only offers a Projects permission under
+# ORGANIZATION permissions — there is no account-level equivalent, so it cannot
+# reach a user-owned board at all. The cost is that `repo` cannot be narrowed to
+# selected repositories the way a fine-grained token can, so keep the expiry
+# short. One token serves every repo.
+# https://github.com/settings/tokens
+GH_PROJECT_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxx

package/config/types.json

@@ -0,0 +1,14 @@
+{
+  "$comment": "THE list of work types — the only place a type is defined. A type is at once a branch prefix (<type>/<description>), a Conventional Commit and PR-title type, and a PR label. release: the bump a commit of that type triggers (minor | patch; `!` or a BREAKING CHANGE footer makes any type major). color: its label's color (description \"Changes for '<type>' branches\"). Key order is precedence: the release PR's title takes the first type among the released commits (scripts/release-title.mjs), so keep the minor types first. Read by commitlint.config.mjs (hook + PR check), scripts/release-title.mjs, actions/pr-checks and actions/auto-pr. config/cliff.toml applies the same bumps (feat minor, the rest patch). This repo uses `refact`, never `refactor`.",
+  "feat": { "release": "minor", "color": "1D76DB" },
+  "fix": { "release": "patch", "color": "D73A4A" },
+  "refact": { "release": "patch", "color": "FBCA04" },
+  "perf": { "release": "patch", "color": "F9D0C4" },
+  "revert": { "release": "patch", "color": "E99695" },
+  "build": { "release": "patch", "color": "0052CC" },
+  "ci": { "release": "patch", "color": "0052CC" },
+  "docs": { "release": "patch", "color": "5319E7" },
+  "test": { "release": "patch", "color": "0E8A16" },
+  "style": { "release": "patch", "color": "C2E0C6" },
+  "chore": { "release": "patch", "color": "BFD4F2" }
+}

package/lib/config.mjs

@@ -0,0 +1,182 @@
+// config.mjs — what a repo should look like on GitHub, read from files only.
+//
+// Every section has two layers: the SHARED one (this package's config/) and
+// the repo's OWN one (<repo>/.github/). For any key the repo's value wins.
+// Nothing here talks to GitHub; lib/sync.mjs compares the result with it.
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, isAbsolute, join } from 'node:path'
+
+// A value that was copied from an .example and never filled in.
+const PLACEHOLDER = /xxxx/i
+
+// KEY=VALUE lines; blank lines and `#` comments skipped, one pair of
+// surrounding quotes stripped.
+export function parseEnvFile(text) {
+  const vars = {}
+  for (const line of text.split(/\r?\n/)) {
+    if (/^\s*(#|$)/.test(line)) continue
+    const i = line.indexOf('=')
+    if (i < 1) continue
+    let value = line.slice(i + 1)
+    if (value.length >= 2 && /^(["']).*\1$/.test(value)) value = value.slice(1, -1)
+    vars[line.slice(0, i).trim()] = value
+  }
+  return vars
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+// Objects merge key by key; arrays and scalars are replaced whole.
+export function deepMerge(base, override) {
+  if (!isPlainObject(base) || !isPlainObject(override)) return override
+  const merged = { ...base }
+  for (const [key, value] of Object.entries(override)) {
+    merged[key] = key in base ? deepMerge(base[key], value) : value
+  }
+  return merged
+}
+
+// Top-level keys starting with `$` (e.g. "$comment") are documentation.
+export function stripDocKeys(value) {
+  if (!isPlainObject(value)) return value
+  return Object.fromEntries(Object.entries(value).filter(([key]) => !key.startsWith('$')))
+}
+
+// [key, current, desired] for every top-level key of DESIRED that differs in CURRENT.
+export function diffTopLevel(desired, current) {
+  const rows = []
+  for (const [key, value] of Object.entries(desired)) {
+    const now = current?.[key]
+    if (JSON.stringify(now) !== JSON.stringify(value)) {
+      rows.push([key, now === undefined ? '(unset)' : JSON.stringify(now), JSON.stringify(value)])
+    }
+  }
+  return rows
+}
+
+function readEnv(file) {
+  return existsSync(file) ? parseEnvFile(readFileSync(file, 'utf8')) : {}
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'))
+  } catch (error) {
+    throw new Error(`${file}: ${error.message}`, { cause: error })
+  }
+}
+
+// mergeJson FILE... — missing files skipped, later wins; null when none exist.
+function mergeJson(...files) {
+  const docs = files.filter(file => existsSync(file)).map(readJson)
+  return docs.length ? stripDocKeys(docs.reduce(deepMerge)) : null
+}
+
+// mergeEnv SHARED REPO — one entry per key: { name, key, value, file, layer }.
+// `layer` says where the value comes from, and flags a repo line that only
+// repeats the shared value (it can be deleted). For secrets, FOO_FILE and FOO
+// are the same key, so either layer can override the other.
+export function mergeEnv(sharedFile, repoFile, { secrets = false } = {}) {
+  const merged = new Map()
+  for (const [file, layer] of [
+    [sharedFile, 'shared'],
+    [repoFile, 'repo'],
+  ]) {
+    for (const [key, value] of Object.entries(readEnv(file))) {
+      const name = secrets ? key.replace(/_FILE$/, '') : key
+      const shared = merged.get(name)
+      let label = layer
+      if (shared?.layer === 'shared' && layer === 'repo') {
+        label =
+          shared.key === key && shared.value === value
+            ? 'repo (same as shared: redundant)'
+            : 'repo (overrides shared)'
+      }
+      merged.set(name, { name, key, value, file, layer: label })
+    }
+  }
+  return [...merged.values()]
+}
+
+// The value to push for a secret entry, refusing empty and placeholder values:
+// a secret cannot be read back to notice a bad write. KEY_FILE=path yields that
+// file's contents (multiline values cannot live in a dotenv file); a relative
+// path is relative to the env file.
+export function secretValue({ key, value, file }) {
+  if (key.endsWith('_FILE')) {
+    let path = value.replace(/^~(?=\/|$)/, homedir())
+    if (!isAbsolute(path)) path = join(dirname(file), path)
+    if (!existsSync(path))
+      throw new Error(`${key} in ${file} points to '${value}', which does not exist.`)
+    return readFileSync(path, 'utf8')
+  }
+  if (!value)
+    throw new Error(`${key} has an empty value in ${file}. Fill it in, or comment the line out.`)
+  if (PLACEHOLDER.test(value))
+    throw new Error(`${key} in ${file} is still a placeholder. Fill it in.`)
+  return value
+}
+
+// Where the shared secrets files live: they are gitignored, so never inside an
+// installed npm package.
+export function sharedSecretsDir(ciRoot, env = process.env) {
+  if (env.CI_SECRETS_DIR) return env.CI_SECRETS_DIR
+  if (existsSync(join(ciRoot, '.git'))) return join(ciRoot, 'config')
+  return join(env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'ebalzan-ci')
+}
+
+function filesIn(dir, pattern) {
+  return existsSync(dir) ? readdirSync(dir).filter(name => pattern.test(name)) : []
+}
+
+// desiredState — the merged config for the repo checked out at REPO_DIR:
+//   variables     [entry]   shared ones are read by the actions at run time
+//   secrets       { repository: [entry], environments: { name: [entry] } }
+//   settings      object | null
+//   rulesets      [{ file, body }]
+export function desiredState({ sharedDir, secretsDir, repoDir }) {
+  const own = join(repoDir, '.github')
+
+  const environments = {}
+  const envNames = [
+    ...filesIn(secretsDir, /^secrets\..+\.env$/),
+    ...filesIn(own, /^secrets\..+\.env$/),
+  ].map(name => name.slice('secrets.'.length, -'.env'.length))
+  for (const env of [...new Set(envNames)].sort()) {
+    environments[env] = mergeEnv(
+      join(secretsDir, `secrets.${env}.env`),
+      join(own, `secrets.${env}.env`),
+      {
+        secrets: true,
+      },
+    )
+  }
+
+  const rulesetFiles = [
+    ...new Set([
+      ...filesIn(join(sharedDir, 'rulesets'), /\.json$/),
+      ...filesIn(join(own, 'rulesets'), /\.json$/),
+    ]),
+  ].sort()
+  const rulesets = rulesetFiles.map(file => {
+    const body = mergeJson(join(sharedDir, 'rulesets', file), join(own, 'rulesets', file))
+    if (!body.name) throw new Error(`Ruleset ${file} has no "name".`)
+    return { file, body }
+  })
+
+  return {
+    variables: mergeEnv(join(sharedDir, 'actions.env'), join(own, 'actions.env')),
+    secrets: {
+      repository: mergeEnv(join(secretsDir, 'secrets.env'), join(own, 'secrets.env'), {
+        secrets: true,
+      }),
+      environments,
+    },
+    settings: mergeJson(join(sharedDir, 'repo-settings.json'), join(own, 'repo-settings.json')),
+    rulesets,
+  }
+}

package/lib/github.mjs

@@ -0,0 +1,132 @@
+// github.mjs — the GitHub side, through the gh CLI (it owns authentication).
+// Every call throws with gh's own message when it fails.
+
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+export function gh(args, { input } = {}) {
+  const result = spawnSync('gh', args, { input, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 })
+  if (result.error) {
+    throw new Error(
+      result.error.code === 'ENOENT'
+        ? 'GitHub CLI (gh) is not installed: https://cli.github.com'
+        : result.error.message,
+    )
+  }
+  if (result.status !== 0) throw new Error(result.stderr.trim() || `gh ${args.join(' ')} failed`)
+  return result.stdout
+}
+
+const ghJson = args => JSON.parse(gh(args) || 'null')
+
+export function isAuthenticated() {
+  try {
+    gh(['auth', 'status'])
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function requireAuth() {
+  gh(['--version'])
+  if (!isAuthenticated()) throw new Error('gh is not authenticated. Run: gh auth login')
+}
+
+// ---- repos -------------------------------------------------------------------
+export const isCheckout = dir => existsSync(join(dir, '.git'))
+
+// OWNER/REPO of the checkout at DIR, or ''. Starts from the git remote, then
+// asks GitHub for the canonical name, so a transferred repo resolves to where
+// it lives now.
+export function detectRepo(dir) {
+  const remote = spawnSync('git', ['-C', dir, 'remote', 'get-url', 'origin'], { encoding: 'utf8' })
+  if (remote.status !== 0) return ''
+  const slug = remote.stdout
+    .trim()
+    .replace(/^(git@|ssh:\/\/git@|https:\/\/)[^/:]+[:/]/, '')
+    .replace(/\.git$/, '')
+  try {
+    return (
+      gh(['repo', 'view', slug, '--json', 'nameWithOwner', '-q', '.nameWithOwner']).trim() || slug
+    )
+  } catch {
+    return slug
+  }
+}
+
+// Creates branch NAME on GitHub at the head of the default branch:
+// { from: the default branch, sha }.
+export function createBranchFromDefault(repo, name) {
+  const from = gh([
+    'repo',
+    'view',
+    repo,
+    '--json',
+    'defaultBranchRef',
+    '-q',
+    '.defaultBranchRef.name',
+  ]).trim()
+  const sha = gh(['api', `repos/${repo}/commits/${from}`, '-q', '.sha']).trim()
+  gh([
+    'api',
+    '-X',
+    'POST',
+    `repos/${repo}/git/refs`,
+    '-f',
+    `ref=refs/heads/${name}`,
+    '-f',
+    `sha=${sha}`,
+  ])
+  return { from, sha }
+}
+
+// ---- variables & secrets -----------------------------------------------------
+// KIND is "variable" or "secret"; ENV, when given, is an environment's scope.
+const scope = (repo, env) => (env ? ['--repo', repo, '--env', env] : ['--repo', repo])
+
+export const listNames = (kind, repo, env) =>
+  ghJson([kind, 'list', ...scope(repo, env), '--json', 'name']).map(entry => entry.name)
+
+export const setVariable = (repo, name, value) =>
+  gh(['variable', 'set', name, '--body', value, '--repo', repo])
+
+export const setSecret = (repo, name, value, env) =>
+  gh(['secret', 'set', name, ...scope(repo, env)], { input: value })
+
+export const deleteEntry = (kind, repo, name, env) =>
+  gh([kind, 'delete', name, ...scope(repo, env)])
+
+// Idempotent: PUT creates the environment or leaves it as it is.
+export const createEnvironment = (repo, env) =>
+  gh(['api', '-X', 'PUT', `repos/${repo}/environments/${env}`])
+
+// ---- settings & rulesets -----------------------------------------------------
+export const getRepo = repo => ghJson(['api', `repos/${repo}`])
+
+export const patchRepo = (repo, settings) =>
+  gh(['api', '-X', 'PATCH', `repos/${repo}`, '--input', '-'], { input: JSON.stringify(settings) })
+
+// The repo's own rulesets (not those inherited from an organization).
+export const listRulesets = repo =>
+  ghJson(['api', `repos/${repo}/rulesets?includes_parents=false`]).filter(
+    ruleset => ruleset.source_type === 'Repository',
+  )
+
+export const createRuleset = (repo, body) =>
+  gh(['api', '-X', 'POST', `repos/${repo}/rulesets`, '--input', '-'], {
+    input: JSON.stringify(body),
+  })
+
+export const updateRuleset = (repo, id, body) =>
+  gh(['api', '-X', 'PUT', `repos/${repo}/rulesets/${id}`, '--input', '-'], {
+    input: JSON.stringify(body),
+  })
+
+export const deleteRuleset = (repo, id) =>
+  gh(['api', '-X', 'DELETE', `repos/${repo}/rulesets/${id}`])
+
+// The API's answer when rulesets need a paid plan (a private repo on GitHub Free).
+export const rulesetsUnavailable = error =>
+  /upgrade to github pro|make this repository public/i.test(error.message)