@ebalzan/ci 0.0.0-stage → 3.0.0

package/bin/gh-reset.sh

@@ -0,0 +1,148 @@
+#!/usr/bin/env bash
+#
+# gh-reset.sh — delete GitHub Actions variables (and optionally secrets) on a repo.
+#
+# Lists what exists on the repo, shows it, and deletes it after a typed
+# confirmation. Destructive and irreversible — use --dry-run first.
+#
+# Repository scope by default (organization-level config is never touched).
+# By default only variables are removed; secret deletion must be requested
+# explicitly. Settings and rulesets are not reset here — edit or delete them in
+# the repo's Settings, or let `ebalzan-ci bootstrap --prune` remove managed
+# rulesets no file defines.
+#
+# --env NAME switches to an ENVIRONMENT's config instead of the repository's.
+# The two scopes are separate namespaces — a repo-scope run cannot see, list, or
+# delete an environment's secrets, which is why clearing deploy credentials
+# needs the flag:
+#
+#   ebalzan-ci reset -R owner/repo --env production --secrets-only --dry-run
+#
+# Note that gh-bootstrap.sh strips a _FILE suffix when it sets a secret, so
+# FOO_FILE in a dotenv file is named FOO on GitHub.
+#
+# Re-running the bootstrap after a reset restores the repo's variables and
+# the merged shared + repo secrets. To remove only keys that no file defines any more, prefer
+# `gh-bootstrap.sh --prune`, which works out the stale set for you.
+#
+# Usage:
+#   ebalzan-ci reset [options]                # repo in the current directory
+#   ebalzan-ci reset -C ../my-repo [options]
+#   ebalzan-ci reset -R owner/repo [options]  # no checkout needed
+#   bin/gh-reset.sh [options]                 # same, from a checkout of ebalzan/ci
+#
+# Options:
+#   -C, --repo-dir DIR    Repo checkout whose remote picks the target (default: .)
+#   -R, --repo OWNER/REPO Target repo (default: detected from DIR's git remote)
+#   -e, --env NAME        Target the environment NAME instead of the repository
+#       --include-secrets Also delete secrets (default: variables only)
+#       --secrets-only    Delete secrets only, leave variables
+#   -m, --match REGEX     Only delete names matching this extended regex
+#   -n, --dry-run         List what would be deleted; delete nothing
+#   -y, --yes             Skip the typed confirmation (dangerous)
+#   -h, --help            Show this help
+#
+# Requirements: gh (GitHub CLI), authenticated with admin on the target repo.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=_lib.sh
+source "$SCRIPT_DIR/_lib.sh"
+
+# ---- args --------------------------------------------------------------------
+REPO=""
+REPO_DIR="."
+ENVIRONMENT=""
+DO_VARS=true
+DO_SECRETS=false
+MATCH=""
+DRY_RUN=false
+ASSUME_YES=false
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -C|--repo-dir)     REPO_DIR="${2:-}"; shift 2 ;;
+    -R|--repo)         REPO="${2:-}"; shift 2 ;;
+    -e|--env)          ENVIRONMENT="${2:-}"; shift 2 ;;
+    --include-secrets) DO_SECRETS=true; shift ;;
+    --secrets-only)    DO_SECRETS=true; DO_VARS=false; shift ;;
+    -m|--match)        MATCH="${2:-}"; shift 2 ;;
+    -n|--dry-run)      DRY_RUN=true; shift ;;
+    -y|--yes)          ASSUME_YES=true; shift ;;
+    -h|--help)         print_help "${BASH_SOURCE[0]}"; exit 0 ;;
+    *)                 die "Unknown option: $1 (try --help)" ;;
+  esac
+done
+
+# ---- preconditions & targets -------------------------------------------------
+require_gh
+require_auth
+[[ -n "$REPO" ]] || REPO="$(detect_repo "$REPO_DIR")"
+[[ -n "$REPO" ]] || die "Could not determine the repo. Pass --repo OWNER/REPO."
+
+# Repo scope unless --env was given. Every gh call takes these flags, so the two
+# scopes can never be mixed up halfway through a run.
+GH_SCOPE=(--repo "$REPO")
+if [[ -n "$ENVIRONMENT" ]]; then
+  gh api "repos/$REPO/environments/$ENVIRONMENT" >/dev/null 2>&1 \
+    || die "Environment '$ENVIRONMENT' does not exist on $REPO."
+  GH_SCOPE+=(--env "$ENVIRONMENT")
+fi
+SCOPE_LABEL="$REPO${ENVIRONMENT:+ · environment: $ENVIRONMENT}"
+
+# List the names of a kind (variable|secret) in scope, filtered by --match.
+list_names() { # list_names KIND
+  local names
+  names="$(gh "$1" list "${GH_SCOPE[@]}" --json name --jq '.[].name' 2>/dev/null || true)"
+  [[ -n "$MATCH" ]] && names="$(printf '%s\n' "$names" | grep -E "$MATCH" || true)"
+  printf '%s' "$names"
+}
+
+# ---- one kind batch ----------------------------------------------------------
+reset_batch() { # reset_batch KIND   (KIND = variable|secret)
+  local kind="$1" names count
+  names="$(list_names "$kind")"
+  count="$(printf '%s\n' "$names" | grep -c . || true)"
+
+  if [[ "$count" -eq 0 ]]; then
+    info "  ${DIM}no ${kind}s${MATCH:+ matching /$MATCH/}${RESET}"
+    return
+  fi
+
+  step "${kind}s to delete from ${BOLD}$SCOPE_LABEL${RESET} ($count)"
+  printf '  - %s\n' $names
+
+  if $DRY_RUN; then return; fi
+
+  if ! $ASSUME_YES; then
+    confirm_typed "$REPO" \
+      "Type '${BOLD}$REPO${RESET}' to permanently delete these $count ${kind}(s) from ${BOLD}$SCOPE_LABEL${RESET}:" \
+      || { warn "Skipped ${kind}s (confirmation did not match)."; return; }
+  fi
+
+  local name
+  while IFS= read -r name; do
+    [[ -n "$name" ]] || continue
+    gh "$kind" delete "$name" "${GH_SCOPE[@]}" && ok "deleted $kind $name"
+  done <<< "$names"
+}
+
+# ---- execute -----------------------------------------------------------------
+info ""
+info "${BOLD}Reset GitHub Actions config${RESET}   ${DIM}repo: $SCOPE_LABEL${MATCH:+ · match: /$MATCH/}${DRY_RUN:+ · dry-run}${RESET}"
+info ""
+
+# An environment holds secrets far more often than variables, and the default
+# is variables-only — so say so rather than reporting an empty run as success.
+if [[ -n "$ENVIRONMENT" ]] && ! $DO_SECRETS; then
+  warn "Only variables are in scope. Environment secrets need --secrets-only (or --include-secrets)."
+fi
+
+if $DO_VARS;    then reset_batch variable; fi
+if $DO_SECRETS; then reset_batch secret;   fi
+
+info ""
+if $DRY_RUN; then
+  ok "Dry run complete — nothing was deleted."
+else
+  ok "${BOLD}Reset complete.${RESET}"
+fi

package/bin/onboard.sh

@@ -0,0 +1,340 @@
+#!/usr/bin/env bash
+#
+# onboard.sh — bring a repo under the shared rules in one step.
+#
+# In the repo's checkout it:
+#   1. creates a branch (ci/onboard-ebalzan-ci) from dev — or from the default
+#      branch when dev does not exist yet;
+#   2. writes the templates/ files: the four thin workflow callers, a starter
+#      .github/actions.env, renovate.json and, for a Node repo, the husky
+#      commit-msg hook. A file that already exists is kept (--force replaces it);
+#   3. adds the .github/secrets*.env files to .gitignore when they are not
+#      ignored yet (before any secret file exists);
+#   4. for a Node repo (package.json): installs this package and husky as
+#      devDependencies, sets `prepare: husky` when no prepare script exists,
+#      and wires the code-style rules of @ebalzan/config — package.json
+#      "prettier" and an eslint.config.mjs — where the repo has no Prettier or
+#      ESLint config of its own (--no-config skips this);
+#   5. commits it all as `ci: onboard <ci repo>`.
+# Then, unless --no-push:
+#   6. creates the dev branch on GitHub if it is missing;
+#   7. tags the repo with REPOS_TOPIC (config/repos.env), so `--all` finds it;
+#   8. runs the bootstrap (variables, secrets, settings, rulesets);
+#   9. pushes the branch. The auto-pr.yml it adds runs on that very push and
+#      opens the tracking issue and the PR into dev. Review and squash-merge it.
+#
+# Usage:
+#   ebalzan-ci onboard [options]          # the repo in the current directory
+#   ebalzan-ci onboard -C ../my-repo [options]
+#
+# Options:
+#   -C, --repo-dir DIR     Checkout of the repo to onboard (default: .)
+#   -R, --repo OWNER/REPO  Its slug (default: from DIR's git remote)
+#       --runs-on LABEL    Runner label for every job (default: ubuntu-latest)
+#       --ref REF          Ref the callers pin (default: v<major of this package>)
+#       --branch NAME      Branch to commit on (default: ci/onboard-ebalzan-ci)
+#       --force            Overwrite files that already exist
+#       --no-npm           Skip the npm installs even when package.json exists
+#       --no-config        Do not wire @ebalzan/config (Prettier, ESLint)
+#       --no-push          Stop after the local commit (no GitHub changes at all)
+#   -n, --dry-run          Show what would happen; change nothing
+#   -y, --yes              Skip the confirmations (also for the bootstrap)
+#   -h, --help             Show this help
+#
+# Requirements: git; gh authenticated with admin on the repo (not needed with
+# --no-push or --dry-run); npm for a Node repo.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CI_ROOT="$(dirname "$SCRIPT_DIR")"
+# shellcheck source=_lib.sh
+source "$SCRIPT_DIR/_lib.sh"
+
+TEMPLATES_DIR="$CI_ROOT/templates"
+REPOS_FILE="$CI_ROOT/config/repos.env"
+CI_REPO="$(unquote "$(env_get "$REPOS_FILE" CI_REPO)")"
+CI_PACKAGE="$(node "$SCRIPT_DIR/_json.mjs" get "$CI_ROOT/package.json" name)"
+CI_VERSION="$(node "$SCRIPT_DIR/_json.mjs" get "$CI_ROOT/package.json" version)"
+TOPIC="$(unquote "$(env_get "$REPOS_FILE" REPOS_TOPIC)")"
+
+# ---- args --------------------------------------------------------------------
+REPO_DIR="."
+REPO=""
+RUNS_ON="ubuntu-latest"
+REF="v${CI_VERSION%%.*}"
+BRANCH="ci/onboard-ebalzan-ci"
+FORCE=false
+NPM=true
+CONFIG=true
+CONFIG_PACKAGE="@ebalzan/config"
+PUSH=true
+DRY_RUN=false
+ASSUME_YES=false
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -C|--repo-dir) REPO_DIR="${2:-}"; shift 2 ;;
+    -R|--repo)     REPO="${2:-}"; shift 2 ;;
+    --runs-on)     RUNS_ON="${2:-}"; shift 2 ;;
+    --ref)         REF="${2:-}"; shift 2 ;;
+    --branch)      BRANCH="${2:-}"; shift 2 ;;
+    --force)       FORCE=true; shift ;;
+    --no-npm)      NPM=false; shift ;;
+    --no-config)   CONFIG=false; shift ;;
+    --no-push)     PUSH=false; shift ;;
+    -n|--dry-run)  DRY_RUN=true; shift ;;
+    -y|--yes)      ASSUME_YES=true; shift ;;
+    -h|--help)     print_help "${BASH_SOURCE[0]}"; exit 0 ;;
+    *)             die "Unknown option: $1 (try --help)" ;;
+  esac
+done
+
+[[ -n "$CI_REPO" ]] || die "CI_REPO is not set in $REPOS_FILE."
+[[ -n "$RUNS_ON" && -n "$REF" && -n "$BRANCH" ]] || die "--runs-on, --ref and --branch need a value."
+
+# ---- preconditions -----------------------------------------------------------
+[[ -d "$REPO_DIR/.git" || -f "$REPO_DIR/.git" ]] || die "$REPO_DIR is not a git checkout."
+REPO_DIR="$(cd "$REPO_DIR" && pwd)"
+git_() { git -C "$REPO_DIR" "$@"; }
+
+if $PUSH && ! $DRY_RUN; then
+  require_gh
+  require_auth
+fi
+if [[ -z "$REPO" ]] && command -v gh >/dev/null 2>&1; then REPO="$(detect_repo "$REPO_DIR")"; fi
+if $PUSH && [[ -z "$REPO" ]]; then
+  die "Could not determine the repo for $REPO_DIR. Pass --repo OWNER/REPO (or --no-push)."
+fi
+if [[ -n "$(git_ status --porcelain)" ]] && ! $DRY_RUN; then
+  die "$REPO_DIR has uncommitted changes. Commit or stash them first."
+fi
+if git_ rev-parse --verify --quiet "refs/heads/$BRANCH" >/dev/null; then
+  die "Branch $BRANCH already exists in $REPO_DIR. Delete it or pass --branch."
+fi
+
+# Branch point: dev if it exists, else the default branch, else HEAD (no remote).
+HAS_ORIGIN=false
+git_ remote get-url origin >/dev/null 2>&1 && HAS_ORIGIN=true
+if $HAS_ORIGIN && ! $DRY_RUN; then git_ fetch --quiet origin || warn "git fetch origin failed; using local refs."; fi
+DEV_EXISTS=false
+if $HAS_ORIGIN && git_ rev-parse --verify --quiet refs/remotes/origin/dev >/dev/null; then
+  DEV_EXISTS=true; BASE_REF="origin/dev"
+elif $HAS_ORIGIN && git_ rev-parse --verify --quiet refs/remotes/origin/HEAD >/dev/null; then
+  BASE_REF="$(git_ symbolic-ref --short refs/remotes/origin/HEAD)"
+else
+  BASE_REF="HEAD"
+fi
+
+IS_NODE=false
+[[ -f "$REPO_DIR/package.json" ]] && IS_NODE=true
+$IS_NODE || CONFIG=false
+
+# present FILE... — the given repo-relative paths that exist, space-separated.
+present() {
+  local f out=""
+  for f in "$@"; do [[ -e "$REPO_DIR/$f" ]] && out+="$f "; done
+  printf '%s' "${out% }"
+}
+PRETTIER_FILES=(.prettierrc .prettierrc.json .prettierrc.json5 .prettierrc.yaml .prettierrc.yml .prettierrc.toml
+  .prettierrc.js .prettierrc.cjs .prettierrc.mjs .prettierrc.ts prettier.config.js prettier.config.cjs
+  prettier.config.mjs prettier.config.ts)
+ESLINT_FILES=(eslint.config.js eslint.config.cjs eslint.config.mjs eslint.config.ts eslint.config.mts
+  eslint.config.cts .eslintrc .eslintrc.js .eslintrc.cjs .eslintrc.json .eslintrc.yaml .eslintrc.yml)
+
+# ---- plan --------------------------------------------------------------------
+# applies REL — whether template REL belongs in this repo at all; when it does
+# not, SKIP_REASON says why.
+SKIP_REASON=""
+applies() {
+  local f
+  case "$1" in
+    .husky/*)
+      $IS_NODE || { SKIP_REASON="no package.json"; return 1; } ;;
+    eslint.config.mjs)
+      $CONFIG || { SKIP_REASON="$($IS_NODE && echo '--no-config' || echo 'no package.json')"; return 1; }
+      # A repo with its own ESLint config extends the preset there; never add a second one.
+      f="$(present "${ESLINT_FILES[@]}")"
+      if [[ -n "$f" && "$f" != eslint.config.mjs ]]; then SKIP_REASON="repo has $f — extend $CONFIG_PACKAGE/eslint/node there"; return 1; fi ;;
+    renovate.json)
+      # Any existing Renovate config is the repo's own; extend the preset there.
+      for f in renovate.json renovate.json5 .renovaterc .renovaterc.json .github/renovate.json .github/renovate.json5; do
+        if [[ -e "$REPO_DIR/$f" ]] && ! $FORCE; then SKIP_REASON="repo has its own Renovate config"; return 1; fi
+      done ;;
+  esac
+  return 0
+}
+
+# Secrets files must be ignored before the first one exists.
+GITIGNORE=false
+if ! git_ check-ignore -q .github/secrets.env || ! git_ check-ignore -q .github/secrets.production.env; then
+  GITIGNORE=true
+fi
+
+# Prettier: point package.json at the shared config unless the repo has its own.
+PRETTIER_SET=false
+PRETTIER_OWN=""
+if $CONFIG; then
+  PRETTIER_OWN="$(present "${PRETTIER_FILES[@]}")"
+  if [[ -z "$PRETTIER_OWN" ]] && [[ "$(cd "$REPO_DIR" && npm pkg get prettier)" == "{}" ]]; then
+    PRETTIER_SET=true
+  elif [[ -z "$PRETTIER_OWN" ]]; then
+    PRETTIER_OWN="package.json \"prettier\""
+  fi
+fi
+# TypeScript is reported, never edited: tsconfig files are JSON with comments.
+TSCONFIG_NOTE=""
+if $CONFIG && [[ -f "$REPO_DIR/tsconfig.json" ]] && ! grep -q "$CONFIG_PACKAGE/tsconfig/" "$REPO_DIR/tsconfig.json"; then
+  TSCONFIG_NOTE="tsconfig.json does not extend $CONFIG_PACKAGE/tsconfig/*.json — add \"extends\" by hand"
+fi
+
+PLAN=()   # "action<TAB>rel" with action = create | overwrite | keep | skip
+while IFS= read -r rel; do
+  if ! applies "$rel"; then PLAN+=("skip	$rel	$SKIP_REASON")
+  elif [[ -e "$REPO_DIR/$rel" ]]; then
+    if $FORCE; then PLAN+=("overwrite	$rel"); else PLAN+=("keep	$rel"); fi
+  else PLAN+=("create	$rel")
+  fi
+done < <(cd "$TEMPLATES_DIR" && find . -type f | sed 's#^\./##' | sort)
+
+info ""
+info "${BOLD}Onboard${RESET}   ${DIM}${REPO:-$(basename "$REPO_DIR")}  ←  $CI_REPO@$REF (runs-on: $RUNS_ON)${RESET}"
+info ""
+info "  ${BOLD}files${RESET} ${DIM}(branch $BRANCH from $BASE_REF)${RESET}"
+for entry in "${PLAN[@]}"; do
+  IFS='	' read -r action rel reason <<< "$entry"
+  case "$action" in
+    create|overwrite) printf '    %-10s %s\n' "$action" "$rel" ;;
+    keep)             printf '    %s%-10s %s (exists — --force replaces it)%s\n' "$DIM" keep "$rel" "$RESET" ;;
+    skip)             printf '    %s%-10s %s (%s)%s\n' "$DIM" skip "$rel" "$reason" "$RESET" ;;
+  esac
+done
+$GITIGNORE && printf '    %-10s %s\n' update ".gitignore (ignore .github/secrets*.env)"
+$PRETTIER_SET && printf '    %-10s %s\n' update "package.json \"prettier\": \"$CONFIG_PACKAGE/prettier\""
+[[ -z "$PRETTIER_OWN" ]] || info "    ${DIM}keep       $PRETTIER_OWN (own Prettier config — extend $CONFIG_PACKAGE/prettier there)${RESET}"
+[[ -z "$TSCONFIG_NOTE" ]] || info "    ${DIM}note       $TSCONFIG_NOTE${RESET}"
+if $IS_NODE && $NPM; then
+  info "  ${BOLD}npm${RESET}"
+  info "    install --save-dev $CI_PACKAGE@^${CI_VERSION%%.*}.0.0 (and husky, if missing)"
+  ! $CONFIG || info "    install --save-dev --save-exact $CONFIG_PACKAGE (and eslint, prettier, if missing)"
+fi
+if $PUSH; then
+  info "  ${BOLD}GitHub${RESET} ${DIM}($REPO)${RESET}"
+  $DEV_EXISTS || info "    create branch dev from $BASE_REF"
+  [[ -z "$TOPIC" ]] || info "    add topic '$TOPIC'"
+  info "    bootstrap: variables, secrets, settings, rulesets"
+  info "    push $BRANCH → auto-pr.yml opens the PR into dev"
+else
+  info "  ${DIM}--no-push: GitHub is left untouched${RESET}"
+fi
+info ""
+
+if $DRY_RUN; then
+  ok "Dry run complete — nothing was changed."
+  exit 0
+fi
+
+# ---- local changes -----------------------------------------------------------
+git_ switch --quiet --no-track -c "$BRANCH" "$BASE_REF"
+
+render() { # render REL — template → repo, placeholders filled in
+  local src="$TEMPLATES_DIR/$1" dest="$REPO_DIR/$1"
+  mkdir -p "$(dirname "$dest")"
+  sed -e "s#__CI_REPO__#$CI_REPO#g" \
+      -e "s#__CI_REPO_NAME__#${CI_REPO#*/}#g" \
+      -e "s#__CI_REF__#$REF#g" \
+      -e "s#__CI_PACKAGE__#$CI_PACKAGE#g" \
+      -e "s#__RUNS_ON__#$RUNS_ON#g" "$src" > "$dest"
+  [[ ! -x "$src" && "$1" != .husky/* ]] || chmod +x "$dest"
+}
+
+for entry in "${PLAN[@]}"; do
+  IFS='	' read -r action rel reason <<< "$entry"
+  case "$action" in create|overwrite) render "$rel"; ok "$action $rel" ;; esac
+done
+
+if $GITIGNORE; then
+  [[ ! -s "$REPO_DIR/.gitignore" ]] || [[ -z "$(tail -c1 "$REPO_DIR/.gitignore")" ]] || printf '\n' >> "$REPO_DIR/.gitignore"
+  cat >> "$REPO_DIR/.gitignore" <<'GITIGNORE'
+
+# Actions secrets, synced by `ebalzan-ci bootstrap`. Never commit them.
+/.github/secrets.env
+/.github/secrets.*.env
+!/.github/secrets*.env.example
+GITIGNORE
+  ok "update .gitignore"
+fi
+
+if $PRETTIER_SET; then
+  (cd "$REPO_DIR" && npm pkg set "prettier=$CONFIG_PACKAGE/prettier") && ok "set package.json \"prettier\""
+fi
+
+if $IS_NODE && $NPM; then
+  step "Installing devDependencies"
+  (cd "$REPO_DIR" && npm install --save-dev --no-audit --no-fund "$CI_PACKAGE@^${CI_VERSION%%.*}.0.0") \
+    || warn "Could not install $CI_PACKAGE (is it published?). The hook skips the local check until it is installed."
+  if ! (cd "$REPO_DIR" && node -e 'const p=require("./package.json");process.exit((p.devDependencies||{}).husky||(p.dependencies||{}).husky?0:1)'); then
+    (cd "$REPO_DIR" && npm install --save-dev --no-audit --no-fund husky) || warn "Could not install husky."
+  fi
+  if [[ "$(cd "$REPO_DIR" && npm pkg get scripts.prepare)" == "{}" ]]; then
+    (cd "$REPO_DIR" && npm pkg set scripts.prepare=husky) && ok "set scripts.prepare = husky"
+  fi
+  if $CONFIG; then
+    # Its peers are pinned by the repo, so add the ones it does not list yet.
+    config_pkgs=("$CONFIG_PACKAGE")
+    for peer in eslint prettier; do
+      (cd "$REPO_DIR" && node -e 'const p=require("./package.json");process.exit({...p.dependencies,...p.devDependencies}[process.argv[1]]?0:1)' "$peer") \
+        || config_pkgs+=("$peer")
+    done
+    (cd "$REPO_DIR" && npm install --save-dev --save-exact --no-audit --no-fund "${config_pkgs[@]}") \
+      || warn "Could not install ${config_pkgs[*]}. Install them before running Prettier or ESLint."
+  fi
+fi
+
+git_ add -A
+if git_ diff --cached --quiet; then
+  warn "Nothing to commit — every file already exists. Use --force to replace them."
+  git_ switch --quiet -
+  git_ branch --quiet -D "$BRANCH"
+  exit 0
+fi
+git_ commit --quiet -m "ci: onboard $CI_REPO shared workflows and rules"
+ok "Committed on $BRANCH: $(git_ log -1 --pretty=%s)"
+
+if ! $PUSH; then
+  info ""
+  ok "${BOLD}Local onboarding done.${RESET} Review with: git -C $REPO_DIR show --stat"
+  info "Then push it yourself, or re-run without --no-push after deleting the branch."
+  exit 0
+fi
+
+# ---- GitHub ------------------------------------------------------------------
+if ! $ASSUME_YES; then
+  confirm "Apply the GitHub steps above to $REPO and push $BRANCH?" || die "Stopped. The local commit on $BRANCH is kept."
+fi
+
+if ! $DEV_EXISTS; then
+  default_branch="$(gh repo view "$REPO" --json defaultBranchRef -q .defaultBranchRef.name)"
+  sha="$(gh api "repos/$REPO/commits/$default_branch" -q .sha)"
+  gh api -X POST "repos/$REPO/git/refs" -f ref=refs/heads/dev -f sha="$sha" >/dev/null
+  ok "created branch dev from $default_branch (${sha:0:7})"
+fi
+
+if [[ -n "$TOPIC" ]]; then
+  gh repo edit "$REPO" --add-topic "$TOPIC" >/dev/null && ok "added topic '$TOPIC'"
+fi
+
+BOOTSTRAP_ARGS=(--repo-dir "$REPO_DIR" --repo "$REPO")
+$ASSUME_YES && BOOTSTRAP_ARGS+=(--yes)
+"$SCRIPT_DIR/gh-bootstrap.sh" "${BOOTSTRAP_ARGS[@]}" \
+  || warn "Bootstrap did not finish; fix the cause and re-run: ebalzan-ci bootstrap -C $REPO_DIR"
+
+git_ push --quiet -u origin "$BRANCH"
+ok "pushed $BRANCH"
+
+info ""
+ok "${BOLD}$REPO is onboarded.${RESET}"
+info "  1. The PR into dev opens within a minute (auto-pr.yml). If it does not:"
+info "     https://github.com/$REPO/compare/dev...$BRANCH"
+info "  2. Add the repo's own checks to .github/workflows/pr-checks.yml and its"
+info "     ship job to release.yml (both have a commented example)."
+[[ -z "$TSCONFIG_NOTE" ]] || info "  ·  $TSCONFIG_NOTE"
+info "  3. Squash-merge the PR, then the dev → main PR: the first release."

package/bin/sync-managed.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+#
+# sync-managed.sh — refresh repos' local copies of ebalzan/ci's managed/ files.
+#
+# DEPRECATED since 2.0. managed/ holds files a repo's local tooling runs —
+# today only the Conventional Commits validator behind the husky commit-msg
+# hook. Repos now run it from the npm package (`ebalzan-ci commit-msg`, see
+# templates/.husky/commit-msg) and keep NO copy. This script remains for repos
+# that still keep a verbatim copy at <repo>/<path>: it keeps those copies
+# current until they move to the package. The PR-title check
+# (actions/pr-title) fails on any copy that differs.
+#
+# Only copies that already exist are updated; --install creates missing ones.
+#
+# Usage:
+#   ebalzan-ci sync-managed [-C DIR | --all] [--check | --install]
+#
+# Options:
+#   -C, --repo-dir DIR   Repo checkout to update (default: current directory)
+#   -a, --all            Every repo config/repos.env selects that has a local
+#                        checkout under $CI_REPOS_ROOT
+#       --check          Report differing copies; change nothing (exit 1 on drift)
+#       --install        Also create copies the repo does not have yet
+#   -h, --help           Show this help
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CI_ROOT="$(dirname "$SCRIPT_DIR")"
+# shellcheck source=_lib.sh
+source "$SCRIPT_DIR/_lib.sh"
+MANAGED_DIR="$CI_ROOT/managed"
+
+REPO_DIRS=()
+ALL=false
+CHECK=false
+INSTALL=false
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -C|--repo-dir) REPO_DIRS+=("${2:-}"); shift 2 ;;
+    -a|--all)      ALL=true; shift ;;
+    --check)       CHECK=true; shift ;;
+    --install)     INSTALL=true; shift ;;
+    -h|--help)     print_help "${BASH_SOURCE[0]}"; exit 0 ;;
+    *)             die "Unknown option: $1 (try --help)" ;;
+  esac
+done
+
+if $ALL; then
+  require_gh
+  require_auth
+  for slug in $(managed_repos "$CI_ROOT/config/repos.env" "$CI_ROOT"); do
+    dir="$(local_checkout "$slug" "$CI_ROOT")"
+    if [[ -n "$dir" ]]; then REPO_DIRS+=("$dir"); else info "${DIM}$slug — no local checkout, skipped${RESET}"; fi
+  done
+fi
+[[ ${#REPO_DIRS[@]} -gt 0 ]] || REPO_DIRS=(".")
+
+drift=0
+for dir in "${REPO_DIRS[@]}"; do
+  [[ -d "$dir" ]] || { warn "No checkout at $dir — skipped."; drift=1; continue; }
+  step "$(basename "$(cd "$dir" && pwd)")"
+  while IFS= read -r rel; do
+    target="$dir/$rel"
+    if [[ ! -f "$target" ]] && ! $INSTALL; then
+      info "  ${DIM}$rel — no local copy (the hook runs it from the package)${RESET}"; continue
+    fi
+    if [[ -f "$target" ]] && cmp -s "$MANAGED_DIR/$rel" "$target"; then
+      ok "$rel up to date"; continue
+    fi
+    if $CHECK; then
+      warn "$rel differs"; drift=1; continue
+    fi
+    mkdir -p "$(dirname "$target")"
+    cp "$MANAGED_DIR/$rel" "$target"
+    chmod +x "$target"
+    ok "$rel updated"
+  done < <(cd "$MANAGED_DIR" && find . -type f | sed 's#^\./##' | sort)
+done
+
+if $CHECK && [[ "$drift" -ne 0 ]]; then die "Managed files out of date — run sync-managed without --check."; fi
+exit 0

package/config/actions.env

@@ -0,0 +1,33 @@
+# SHARED GitHub Actions VARIABLES — the house rules every repo calling the
+# shared workflows 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: …@v2`
+# (actions/auto-work-items/src/sharedVars.ts) 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.
+#
+# Only values that differ from the code defaults live here
+# (actions/auto-work-items/src/config.ts, describe.ts, project.ts): priority
+# comes from TYPE_CONFIG, size defaults to M, estimate to 1, dates to
+# today → +7 days, strict metadata on, the board owner is the repo owner, and
+# 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.
+#
+# Full key reference: docs/CONFIGURATION.md.
+
+# Claude model that writes the issue/PR descriptions (describe.ts). Kept here,
+# not just as the code default, so it can be switched without a code change.
+# AUTO_DESCRIBE_EFFORT: low | medium | high | xhigh | max — ignored for Haiku,
+# which does not accept it.
+AUTO_DESCRIBE_MODEL=claude-sonnet-5-5
+AUTO_DESCRIBE_EFFORT=low
+
+AUTO_SIZE_MAP_JSON={"feat":"M","fix":"S","docs":"S","style":"S","refact":"M","perf":"M","test":"S","build":"S","ci":"S","chore":"S","revert":"S"}
+AUTO_ESTIMATE_MAP_JSON={"feat":"3","fix":"2","docs":"1","style":"1","refact":"2","perf":"2","test":"1","build":"1","ci":"1","chore":"1","revert":"1"}

package/config/repo-settings.json

@@ -0,0 +1,10 @@
+{
+  "$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. Reference: docs/REPO_RULES.md.",
+  "allow_squash_merge": true,
+  "allow_merge_commit": false,
+  "allow_rebase_merge": true,
+  "squash_merge_commit_title": "PR_TITLE",
+  "squash_merge_commit_message": "COMMIT_MESSAGES",
+  "delete_branch_on_merge": true,
+  "allow_update_branch": true
+}

package/config/repos.env

@@ -0,0 +1,25 @@
+# Which repos `--all` acts on (bin/gh-bootstrap.sh, bin/sync-managed.sh).
+# The union of both lists below is used; a repo listed twice is synced once.
+#
+# Discovery by topic (recommended): every repo of REPOS_OWNER tagged with
+# REPOS_TOPIC. `ebalzan-ci onboard` adds the topic, so onboarding a repo needs
+# no edit here. Leave REPOS_TOPIC empty to turn discovery off.
+REPOS_TOPIC=ebalzan-ci
+# Account whose repos are searched for the topic. Empty = the account gh is
+# logged in as (`gh api user`).
+REPOS_OWNER=
+
+# Explicit extra repos, as OWNER/REPO slugs separated by spaces — e.g. repos of
+# another account or organization you administer.
+REPOS=
+
+# Where `--all` looks for local checkouts: <CI_REPOS_ROOT>/<repo name>. A repo
+# with a local checkout gets its gitignored .github/secrets*.env synced too; one
+# without is synced from its default branch through the API (variables,
+# settings, rulesets, shared secrets — never its own secrets, which only exist
+# locally). Default: the directory holding this checkout. Override with the
+# CI_REPOS_ROOT environment variable.
+
+# Where this repo lives — the slug every caller's `uses:` names, and what
+# `ebalzan-ci onboard` writes into the templates. Change it only if you fork.
+CI_REPO=ebalzan/ci

package/config/rulesets/protect-dev.json

@@ -0,0 +1,10 @@
+{
+  "$comment": "dev is the integration branch: it cannot be deleted. Force-pushes stay allowed because release.yml's sync-dev job force-points dev at each release commit. Reference: docs/REPO_RULES.md.",
+  "name": "ci: protect dev",
+  "target": "branch",
+  "enforcement": "active",
+  "conditions": {
+    "ref_name": { "include": ["refs/heads/dev"], "exclude": [] }
+  },
+  "rules": [{ "type": "deletion" }]
+}

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 job only fast-forwards it, so nothing in the pipeline needs a bypass. Reference: docs/REPO_RULES.md.",
+  "name": "ci: protect main",
+  "target": "branch",
+  "enforcement": "active",
+  "conditions": {
+    "ref_name": { "include": ["refs/heads/main"], "exclude": [] }
+  },
+  "rules": [{ "type": "deletion" }, { "type": "non_fast_forward" }]
+}