setup-git-repo 1.0.0

package/src/template.mjs

@@ -0,0 +1,142 @@
+import { readdirSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+
+/**
+ * Every optional badge in the template README carries a `<!-- badge:NAME -->`
+ * marker at the start of its line. A badge whose value the user did not supply
+ * would render as a broken image pointing at a literal `{{DOI}}`, so its whole
+ * line is dropped; a badge that is kept has only its marker removed.
+ *
+ * Maps marker name -> the placeholders that badge needs to be renderable.
+ */
+export const OPTIONAL_BADGES = {
+  doi: ["DOI"],
+  docs: ["DOCS_URL"],
+  api: ["API_URL"],
+  youtube: ["YOUTUBE_URL"],
+  npm: ["PACKAGE"],
+  uptime: ["UPTIME_ID"],
+  discord: ["DISCORD_ID", "DISCORD_INVITE"],
+};
+
+const BADGE_MARKER = /<!--\s*badge:([a-z0-9-]+)\s*-->/i;
+
+/** Badge names whose placeholders all have a non-empty value. */
+export function configuredBadges(values) {
+  return new Set(
+    Object.entries(OPTIONAL_BADGES)
+      .filter(([, keys]) => keys.every((k) => typeof values[k] === "string" && values[k].trim() !== ""))
+      .map(([name]) => name),
+  );
+}
+
+/**
+ * Drop the lines of unconfigured badges and strip markers from the rest.
+ *
+ * Operates line by line, which is why the template keeps one `<a>` per line.
+ */
+export function applyBadges(content, values) {
+  const keep = configuredBadges(values);
+  const out = [];
+
+  for (const line of content.split("\n")) {
+    const match = line.match(BADGE_MARKER);
+    if (!match) {
+      out.push(line);
+      continue;
+    }
+    if (!keep.has(match[1].toLowerCase())) continue;
+    // Normalize indentation: the marker sits at column 0, but the badge
+    // lines around it are indented, and the block is read by humans.
+    out.push(`    ${line.replace(BADGE_MARKER, "").trimStart()}`);
+  }
+
+  return out.join("\n");
+}
+
+/**
+ * Replace every `{{KEY}}` with its value.
+ *
+ * An unknown or empty key is left as-is rather than replaced with an empty
+ * string: a visible `{{THING}}` in the output is a bug you notice, whereas a
+ * silent blank in a URL is one you ship.
+ */
+export function substitute(content, values) {
+  return content.replace(/\{\{([A-Z0-9_]+)\}\}/g, (whole, key) => {
+    const value = values[key];
+    return typeof value === "string" && value.trim() !== "" ? value : whole;
+  });
+}
+
+/** Render one template file: badge pruning first, then placeholders. */
+export function render(content, values) {
+  return substitute(applyBadges(content, values), values);
+}
+
+/** Recursively list files under `dir`, as paths relative to it, sorted. */
+export function collectFiles(dir) {
+  const out = [];
+
+  const walk = (current) => {
+    for (const entry of readdirSync(current).sort()) {
+      const full = join(current, entry);
+      if (statSync(full).isDirectory()) {
+        // Nothing in the template needs these, and copying a stale build into a
+        // fresh repo is worse than useless.
+        if (entry === "node_modules" || entry === ".turbo" || entry === "dist") continue;
+        walk(full);
+        continue;
+      }
+      out.push(relative(dir, full).split(sep).join("/"));
+    }
+  };
+
+  walk(dir);
+  return out.sort();
+}
+
+/**
+ * Decide what to do with each template file given what already exists.
+ *
+ * `only` narrows the run to a subset — the `--workflows-only` / `--badges-only`
+ * flags — matched as path prefixes.
+ */
+export function planFiles(files, { exists, force = false, only = null }) {
+  const plan = { write: [], overwrite: [], skip: [] };
+
+  for (const file of files) {
+    if (only && !only.some((prefix) => file === prefix || file.startsWith(`${prefix}/`))) {
+      continue;
+    }
+    if (!exists(file)) {
+      plan.write.push(file);
+    } else if (force) {
+      plan.overwrite.push(file);
+    } else {
+      plan.skip.push(file);
+    }
+  }
+
+  return plan;
+}
+
+/**
+ * Where a template file lands in the target repo.
+ *
+ * `gitignore` becomes `.gitignore`. It is stored without the dot because npm
+ * strips `.gitignore` out of published tarballs — a template that carried one
+ * would work from a checkout and silently lose the file when installed from the
+ * registry.
+ */
+export function destinationFor(file) {
+  if (file === "gitignore") return ".gitignore";
+  return file;
+}
+
+/** Path prefixes selected by the `--*-only` flags. */
+export const SUBSETS = {
+  workflows: [".github"],
+  badges: ["README.md"],
+  docs: ["docs"],
+  turbo: ["turbo.json", "package.json", "vitest.config.ts"],
+};

package/template/.github/scripts/next-free-version.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+/**
+ * Print the next version of a package that the registry has not already spent.
+ *
+ * Bumping one patch above the `latest` dist-tag is not enough. `latest` lags
+ * any version that an interrupted publish staged, and npm answers a PUT for one
+ * of those with `E409 ... Cannot publish over previously staged version`. Those
+ * numbers show up in the full version list and in the release timeline, so both
+ * are consulted here.
+ *
+ *   node .github/scripts/next-free-version.mjs <package-name> <current-version>
+ */
+import { execFileSync } from "node:child_process";
+
+const [, , name, current] = process.argv;
+
+if (!name || !current) {
+  console.error("usage: next-free-version.mjs <package-name> <current-version>");
+  process.exit(2);
+}
+
+/** Run `npm view` and parse JSON, treating any failure as "no data". */
+function npmView(field) {
+  try {
+    const out = execFileSync("npm", ["view", name, field, "--json"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return JSON.parse(out);
+  } catch {
+    return null;
+  }
+}
+
+const taken = new Set();
+
+const versions = npmView("versions");
+if (Array.isArray(versions)) for (const v of versions) taken.add(v);
+else if (typeof versions === "string") taken.add(versions);
+
+// `time` carries every version the registry has a timestamp for, including ones
+// that were unpublished or staged and never completed.
+const time = npmView("time");
+if (time && typeof time === "object") {
+  for (const key of Object.keys(time)) {
+    if (key !== "created" && key !== "modified") taken.add(key);
+  }
+}
+
+const parse = (v) => {
+  const [core] = String(v).split(/[-+]/);
+  const parts = core.split(".").map((n) => Number.parseInt(n, 10) || 0);
+  return [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0];
+};
+
+// Start from the highest number the registry knows about, not from `current`:
+// a local version behind the registry would otherwise propose versions that are
+// all taken, one refused publish at a time.
+let [major, minor, patch] = parse(current);
+for (const v of taken) {
+  const [ma, mi, pa] = parse(v);
+  if (ma > major || (ma === major && (mi > minor || (mi === minor && pa > patch)))) {
+    [major, minor, patch] = [ma, mi, pa];
+  }
+}
+
+let next;
+do {
+  patch += 1;
+  next = `${major}.${minor}.${patch}`;
+} while (taken.has(next));
+
+console.log(next);

package/template/.github/workflows/auto-merge-and-create-prs.yml

@@ -0,0 +1,96 @@
+# A twice-daily sweep that keeps branches from going stale:
+#   1. merges open PRs that are already clean, approved (or unreviewed) and green
+#   2. opens a PR for any pushed branch that never got one
+#
+# Both halves are idempotent, so a delayed or duplicated run is harmless.
+name: Auto-merge PRs and create missing PRs
+
+on:
+  schedule:
+    # 00:00 and 12:00 UTC. Scheduled workflows can be delayed for hours during
+    # periods of high GitHub Actions load — never rely on the exact minute.
+    - cron: "0 */12 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: auto-merge-and-create-prs
+  cancel-in-progress: false
+
+jobs:
+  maintain-pull-requests:
+    runs-on: ubuntu-latest
+    env:
+      GH_TOKEN: ${{ secrets.GIT_TOKEN }}
+      GIT_TOKEN: ${{ secrets.GIT_TOKEN }}
+      BASE_BRANCH: ${{ github.event.repository.default_branch }}
+    steps:
+      - name: Merge eligible existing pull requests
+        env:
+          REPOSITORY: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+
+          # Eligible means: not a draft, mergeable with no conflicts (CLEAN),
+          # either approved or not reviewed at all, and every check that
+          # reported came back SUCCESS/SKIPPED/NEUTRAL.
+          gh pr list \
+            --repo "$REPOSITORY" \
+            --state open \
+            --json number,isDraft,mergeStateStatus,reviewDecision,statusCheckRollup \
+            --jq '.[] | select(.isDraft == false) | select(.mergeStateStatus == "CLEAN") | select((.reviewDecision == "APPROVED") or (.reviewDecision == "")) | select(all(.statusCheckRollup[]?; (.conclusion == "SUCCESS" or .conclusion == "SKIPPED" or .conclusion == "NEUTRAL"))) | .number' \
+          | while read -r pr_number; do
+              echo "Attempting to merge PR #${pr_number}"
+              gh pr merge "$pr_number" \
+                --repo "$REPOSITORY" \
+                --merge \
+                --delete-branch \
+                --auto || echo "Could not merge PR #${pr_number}; it may require review, checks, or conflict resolution."
+            done
+
+      - name: Create pull requests for branches without one
+        env:
+          REPOSITORY: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+
+          # No actions/checkout above: this step only needs refs, so it fetches
+          # them into an empty workspace instead of paying for a full checkout.
+          git config --global --add safe.directory "$GITHUB_WORKSPACE"
+          git init -q "$GITHUB_WORKSPACE"
+          cd "$GITHUB_WORKSPACE"
+          git remote add origin "https://x-access-token:${GIT_TOKEN}@github.com/${REPOSITORY}.git"
+          git fetch --quiet origin '+refs/heads/*:refs/remotes/origin/*'
+
+          base_sha="$(git rev-parse "origin/${BASE_BRANCH}")"
+
+          git for-each-ref --format='%(refname:strip=3)' refs/remotes/origin \
+            | grep -Ev "^(HEAD|${BASE_BRANCH})$" \
+            | while read -r branch; do
+                open_pr="$(gh pr list --repo "$REPOSITORY" --state open --head "$branch" --json number --jq 'length')"
+                merged_pr="$(gh pr list --repo "$REPOSITORY" --state merged --head "$branch" --json number --jq 'length')"
+                branch_sha="$(git rev-parse "origin/${branch}")"
+
+                # A merged PR counts: reopening one for a branch whose work
+                # already landed would create an empty, permanently open PR.
+                if [ "$open_pr" -gt 0 ] || [ "$merged_pr" -gt 0 ]; then
+                  echo "Skipping ${branch}: a pull request already exists or was previously merged."
+                  continue
+                fi
+
+                if git merge-base --is-ancestor "$branch_sha" "$base_sha"; then
+                  echo "Skipping ${branch}: it is already contained in ${BASE_BRANCH}."
+                  continue
+                fi
+
+                echo "Creating PR for ${branch} -> ${BASE_BRANCH}"
+                gh pr create \
+                  --repo "$REPOSITORY" \
+                  --head "$branch" \
+                  --base "$BASE_BRANCH" \
+                  --title "Merge ${branch} into ${BASE_BRANCH}" \
+                  --body "Automated pull request for branch \`${branch}\`."
+              done

package/template/.github/workflows/auto-merge-claude.yml

@@ -0,0 +1,50 @@
+# Enables auto-merge on pull requests opened by trusted agents and maintainers,
+# so an agent-authored change lands on its own once required checks pass.
+#
+# `--auto` is the safe path: GitHub holds the merge until branch protection is
+# satisfied. It only works when "Allow auto-merge" is on in repo settings AND
+# the base branch has protection with at least one required status check —
+# without both, GitHub rejects the flag and the fallback below merges directly.
+# On a repo with no branch protection, that fallback merges without waiting for
+# CI, which is why the actor allowlist matters.
+name: Auto-merge agent PRs
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  auto-merge:
+    runs-on: ubuntu-latest
+    # Extend this list with the bots and maintainers whose PRs may self-merge.
+    if: >
+      github.actor == 'claude[bot]' ||
+      github.actor == 'anthropic-claude[bot]' ||
+      github.actor == '{{OWNER}}'
+    steps:
+      - name: Enable auto-merge (or merge directly)
+        env:
+          # A PAT rather than GITHUB_TOKEN: merges made with GITHUB_TOKEN do not
+          # trigger further workflows, so deploy/publish runs on the default
+          # branch would never fire.
+          GH_TOKEN: ${{ secrets.GIT_TOKEN }}
+          PR: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}
+          HEAD_REF: ${{ github.head_ref }}
+        run: |
+          # Long-lived branches must survive their own merges.
+          case "$HEAD_REF" in
+            production|prod|staging|develop) MERGE_OPTS="--squash" ;;
+            *) MERGE_OPTS="--squash --delete-branch" ;;
+          esac
+
+          if gh pr merge "$PR" --repo "$REPO" $MERGE_OPTS --auto; then
+            echo "Auto-merge enabled for PR #$PR"
+          else
+            echo "Auto-merge unavailable, attempting direct merge"
+            gh pr merge "$PR" --repo "$REPO" $MERGE_OPTS
+          fi

package/template/.github/workflows/deploy-test-reports.yml

@@ -0,0 +1,85 @@
+# Publishes a browsable HTML test report to Cloudflare Workers on every push to
+# the default branch, so the README's "Test Report" badge links somewhere real.
+name: Test Reports
+
+on:
+  push:
+    branches: [{{DEFAULT_BRANCH}}]
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    name: Generate & Deploy Test Reports
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: bun install --ignore-scripts
+
+      - name: Build workspace libraries consumed via dist
+        run: bunx turbo run build
+
+      - name: Run tests with HTML reporter
+        run: bun run test:report
+        # A red suite must still publish its report — that report is how you
+        # find out what went red.
+        continue-on-error: true
+
+      # What the step above must not do is leave `dist` missing: `wrangler
+      # deploy` treats an absent `assets.directory` as a hard error, so the run
+      # would end on a config error instead of on the test signal. Publish a
+      # placeholder rather than lose the deploy.
+      - name: Ensure a report exists to deploy
+        env:
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          if [ -f apps/test-reports/dist/index.html ]; then
+            exit 0
+          fi
+          echo "::warning::Vitest wrote no HTML report; deploying a placeholder page."
+          mkdir -p apps/test-reports/dist
+          cat > apps/test-reports/dist/index.html <<HTML
+          <!doctype html>
+          <html lang="en">
+          <head>
+          <meta charset="utf-8">
+          <meta name="viewport" content="width=device-width, initial-scale=1">
+          <title>Test report unavailable</title>
+          <style>
+          :root { color-scheme: light dark; }
+          body { margin: 0; min-height: 100vh; display: grid; place-items: center;
+                 font: 16px/1.6 system-ui, sans-serif; padding: 24px; }
+          main { max-width: 34rem; }
+          h1 { font-size: 1.25rem; margin: 0 0 .75rem; }
+          p { margin: 0 0 .75rem; opacity: .85; }
+          </style>
+          </head>
+          <body>
+          <main>
+          <h1>Test report unavailable</h1>
+          <p>The last run of the test suite ended before the HTML reporter could
+          write a report, so there is nothing to show here yet.</p>
+          <p><a href="$RUN_URL">Open the workflow run</a> for the full output.</p>
+          <p>Commit $GITHUB_SHA</p>
+          </main>
+          </body>
+          </html>
+          HTML
+
+      - name: Deploy to Cloudflare Workers
+        working-directory: apps/test-reports
+        run: npx wrangler deploy
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+
+      - name: Upload report artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-reports
+          path: apps/test-reports/dist/
+          if-no-files-found: ignore