repokeeper 0.2.3 → 0.3.0

package/README.md

@@ -56,10 +56,12 @@ adds; jobs you add yourself are left alone, and so is the formatting of the rest
 
 The script stack runs ShellCheck and `shfmt -d` on `*.sh` (format with `shfmt -w` before pushing)
 and PSScriptAnalyzer on `*.ps1`, which fails on errors and warnings (not on information-level rules). To
-choose the rules yourself, add a `PSScriptAnalyzerSettings.psd1` at the repository root; the job then uses it:
+choose the rules yourself, add a `PSScriptAnalyzerSettings.psd1` at the repository root; the job then
+uses it instead of its own filter, so keep `Severity` in it unless you want information-level rules too:
 
 ```powershell
 @{
+    Severity     = @('Error', 'Warning')
     # installers print for the person running them
     ExcludeRules = @('PSAvoidUsingWriteHost')
 }
@@ -75,6 +77,33 @@ work:
   and issues write access). Without it the release pull request is opened with `GITHUB_TOKEN`, and
   GitHub does not run CI on pull requests opened that way.
 
+Set `modules.drift: true` to add a `repokeeper` job to `ci.yml` that runs `repokeeper check` with
+the version that wrote the standard, so a pull request that edits a managed file fails until the edit
+is resolved.
+
+## GitHub settings
+
+`repokeeper github apply` brings the repository's settings in line with the `github:` section of
+`.repokeeper.yml`. Only the keys you write are managed; anything left out stays as it is.
+
+```yaml
+github:
+  description: Keeps repositories on one standard
+  topics: [cli, conventional-commits]
+  merge: { squash: true, merge_commit: false, rebase: false, delete_branch_on_merge: true }
+  security: { dependabot_alerts: true, dependabot_security_updates: true }
+  protect:                  # a ruleset named "repokeeper" on the default branch; false removes it
+    require_pull_request: true
+    required_approvals: 0
+    required_checks: ["commits / commitlint"]   # check names exactly as pull requests show them
+    allow_force_push: false
+```
+
+It prints every change first and applies them with `--yes`, or after you confirm in a terminal;
+`--dry-run` only prints. The token comes from `GITHUB_TOKEN` or `gh auth token` and needs admin
+access to the repository. Legacy branch protection, visibility, secrets and collaborators are never
+touched.
+
 ## License
 
 MIT

package/dist/cli.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 import { realpathSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 import { checkCommand } from "./commands/check.js";
+import { githubApplyCommand } from "./commands/github.js";
 import { initCommand } from "./commands/init.js";
 import { updateCommand } from "./commands/update.js";
 import { STACK_IDS } from "./config/types.js";
@@ -15,6 +17,7 @@ export const USAGE = [
     "  init    detect stacks, write .repokeeper.yml and apply the standard",
     "  check   report drift from the standard without writing (exit 1 on drift)",
     "  update  move to the standard of this repokeeper version and resync",
+    "  github apply  diff the GitHub settings against .repokeeper.yml and apply them",
     "",
     "options:",
     "  --dry-run        show what would change without writing",
@@ -24,6 +27,7 @@ export const USAGE = [
     "  --stack <id>     stack to use instead of detection (init, repeatable)",
     "  --relock         rebuild .repokeeper/lock.json from the current files (init)",
     "  --json           machine-readable output (check)",
+    "  -y, --yes        apply without asking (github apply)",
     "  -v, --version    print the version",
 ].join("\n");
 const toPosix = (path) => path.replace(/\\/g, "/").replace(/^\.\//, "");
@@ -42,6 +46,7 @@ export async function run(argv, io) {
                 stack: { type: "string", multiple: true, default: [] },
                 relock: { type: "boolean", default: false },
                 json: { type: "boolean", default: false },
+                yes: { type: "boolean", short: "y", default: false },
                 version: { type: "boolean", short: "v", default: false },
                 help: { type: "boolean", short: "h", default: false },
             },
@@ -70,6 +75,7 @@ export async function run(argv, io) {
             stacks: stacks,
             relock: values.relock,
             json: values.json,
+            yes: values.yes,
         };
         if (command === "init")
             return await initCommand(io.cwd, options, io);
@@ -77,6 +83,11 @@ export async function run(argv, io) {
             return await checkCommand(io.cwd, options, io);
         if (command === "update")
             return await updateCommand(io.cwd, options, io);
+        if (command === "github") {
+            if (positionals[1] !== "apply")
+                throw new UsageError("usage: repokeeper github apply [--dry-run] [--yes]");
+            return await githubApplyCommand(io.cwd, options, io);
+        }
         throw new UsageError(`unknown command: ${command}`);
     }
     catch (error) {
@@ -94,12 +105,22 @@ export async function run(argv, io) {
         throw error;
     }
 }
+async function askYesNo(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return /^y(es)?$/i.test((await rl.question(`${question} [y/N] `)).trim());
+    }
+    finally {
+        rl.close();
+    }
+}
 const invokedPath = process.argv[1];
 if (invokedPath !== undefined && realpathSync(invokedPath) === fileURLToPath(import.meta.url)) {
     run(process.argv.slice(2), {
         cwd: process.cwd(),
         out: (line) => process.stdout.write(`${line}\n`),
         err: (line) => process.stderr.write(`${line}\n`),
+        ...(process.stdin.isTTY ? { confirm: askYesNo } : {}),
     }).then((code) => {
         process.exitCode = code;
     });

package/dist/commands/github.js

@@ -0,0 +1,36 @@
+import { loadConfig } from "../config/load.js";
+import { UsageError } from "../errors.js";
+import { repoInfo } from "../git.js";
+import { resolveToken, restApi } from "../github/api.js";
+import { planGithub } from "../github/settings.js";
+/** `repokeeper github apply`: diff the repository's GitHub settings against `github:` and apply on confirmation. */
+export async function githubApplyCommand(root, options, io) {
+    const config = await loadConfig(root);
+    const repo = await repoInfo(root);
+    if (!repo.owner)
+        throw new UsageError("the origin remote is not a GitHub repository");
+    const slug = `${repo.owner}/${repo.name}`;
+    const api = io.githubApi ?? restApi(await resolveToken());
+    const changes = await planGithub(api, repo.owner, repo.name, config.github ?? {});
+    if (changes.length === 0) {
+        io.out(`GitHub settings of ${slug} match .repokeeper.yml`);
+        return 0;
+    }
+    for (const change of changes)
+        io.out(`change     ${change.setting}: ${change.from} -> ${change.to}`);
+    if (options.dryRun) {
+        io.out("dry run: nothing applied");
+        return 0;
+    }
+    const question = `apply ${changes.length} change(s) to ${slug}?`;
+    const confirmed = options.yes || (io.confirm ? await io.confirm(question) : false);
+    if (!confirmed) {
+        io.out("nothing applied; pass --yes to apply");
+        return 1;
+    }
+    for (const change of changes) {
+        await change.apply(api);
+        io.out(`applied    ${change.setting}`);
+    }
+    return 0;
+}

package/dist/config/load.js

@@ -59,6 +59,7 @@ function withDefaults(data) {
             release: modules.release ?? true,
             deps: modules.deps ?? true,
             gitignore: modules.gitignore ?? true,
+            drift: modules.drift ?? false,
             health: modules.health,
         },
         owned: data.owned ?? [],

package/dist/config/schema.js

@@ -20,6 +20,7 @@ export const configSchema = {
                 release: flag,
                 deps: flag,
                 gitignore: flag,
+                drift: flag,
                 health: {
                     anyOf: [
                         { const: false },
@@ -40,6 +41,39 @@ export const configSchema = {
         },
         owned: { type: "array", items: { type: "string", minLength: 1 } },
         stack_options: { type: "object" },
-        github: { type: "object" },
+        github: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                default_branch: { type: "string", minLength: 1 },
+                description: { type: "string" },
+                topics: { type: "array", uniqueItems: true, items: { type: "string", pattern: "^[a-z0-9][a-z0-9-]{0,49}$" } },
+                merge: {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: { squash: flag, merge_commit: flag, rebase: flag, delete_branch_on_merge: flag },
+                },
+                security: {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: { dependabot_alerts: flag, dependabot_security_updates: flag },
+                },
+                protect: {
+                    anyOf: [
+                        { const: false },
+                        {
+                            type: "object",
+                            additionalProperties: false,
+                            properties: {
+                                require_pull_request: flag,
+                                required_approvals: { type: "integer", minimum: 0, maximum: 10 },
+                                required_checks: { type: "array", uniqueItems: true, items: { type: "string", minLength: 1 } },
+                                allow_force_push: flag,
+                            },
+                        },
+                    ],
+                },
+            },
+        },
     },
 };

package/dist/config/types.js

@@ -18,6 +18,7 @@ export function defaultConfig(input) {
             release: true,
             deps: true,
             gitignore: true,
+            drift: false,
             health: { license: "MIT", copyright: input.copyright, contact: input.contact, codeowners: input.codeowners },
         },
         owned: [],

package/dist/errors.js

@@ -18,6 +18,12 @@ export class UsageError extends RepokeeperError {
         super(message, 2);
     }
 }
+/** A GitHub API call failed; nothing on disk was touched. */
+export class ApiError extends RepokeeperError {
+    constructor(message) {
+        super(message, 3);
+    }
+}
 /** `.repokeeper/lock.json` is unreadable; the repository state is unknown, which counts as drift. */
 export class LockError extends RepokeeperError {
     constructor(message) {

package/dist/github/api.js

@@ -0,0 +1,49 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { ApiError } from "../errors.js";
+const execFileAsync = promisify(execFile);
+/** `GITHUB_TOKEN`, or the token of the GitHub CLI. */
+export async function resolveToken(env = process.env) {
+    if (env.GITHUB_TOKEN)
+        return env.GITHUB_TOKEN;
+    try {
+        const { stdout } = await execFileAsync("gh", ["auth", "token"], { encoding: "utf8" });
+        if (stdout.trim())
+            return stdout.trim();
+    }
+    catch {
+        // fall through to the error below
+    }
+    throw new ApiError("no GitHub token: set GITHUB_TOKEN or sign in with `gh auth login`");
+}
+export function restApi(token, base = "https://api.github.com") {
+    return {
+        async request(method, path, body) {
+            let response;
+            try {
+                response = await fetch(`${base}${path}`, {
+                    method,
+                    headers: {
+                        accept: "application/vnd.github+json",
+                        authorization: `Bearer ${token}`,
+                        "x-github-api-version": "2022-11-28",
+                        ...(body === undefined ? {} : { "content-type": "application/json" }),
+                    },
+                    body: body === undefined ? undefined : JSON.stringify(body),
+                });
+            }
+            catch (error) {
+                throw new ApiError(`GitHub API ${method} ${path} failed: ${error.message}`);
+            }
+            const text = await response.text();
+            let data = null;
+            try {
+                data = text ? JSON.parse(text) : null;
+            }
+            catch {
+                data = text;
+            }
+            return { status: response.status, data };
+        },
+    };
+}

package/dist/github/settings.js

@@ -0,0 +1,184 @@
+import { ApiError } from "../errors.js";
+export const RULESET_NAME = "repokeeper";
+function expect2xx(response, what, repo) {
+    if (response.status < 400)
+        return response;
+    const message = response.data?.message ?? `HTTP ${response.status}`;
+    const access = response.status === 403 || response.status === 404
+        ? `; this needs admin access to ${repo} (a token with the repo scope, or Administration: write)`
+        : "";
+    throw new ApiError(`${what} failed: ${message}${access}`);
+}
+const show = (value) => value === undefined || value === null || value === ""
+    ? "(none)"
+    : Array.isArray(value)
+        ? value.join(", ") || "(none)"
+        : String(value);
+const MERGE_FIELDS = {
+    squash: "allow_squash_merge",
+    merge_commit: "allow_merge_commit",
+    rebase: "allow_rebase_merge",
+    delete_branch_on_merge: "delete_branch_on_merge",
+};
+function summarize(rules) {
+    const pr = rules.find((r) => r.type === "pull_request");
+    const checks = rules.find((r) => r.type === "required_status_checks");
+    return {
+        pullRequest: pr !== undefined,
+        approvals: pr?.parameters?.required_approving_review_count ?? 0,
+        checks: (checks?.parameters?.required_status_checks ?? []).map((c) => c.context).sort(),
+        forcePush: !rules.some((r) => r.type === "non_fast_forward"),
+    };
+}
+function describeRules(summary) {
+    if (summary === null)
+        return "(none)";
+    const parts = [
+        summary.pullRequest ? `pull request required (${summary.approvals} approvals)` : "no pull request required",
+        summary.checks.length > 0 ? `checks: ${summary.checks.join(", ")}` : "no required checks",
+        summary.forcePush ? "force push allowed" : "no force push",
+    ];
+    return parts.join("; ");
+}
+function desiredRules(protect) {
+    const rules = [];
+    if (protect.require_pull_request ?? true) {
+        rules.push({
+            type: "pull_request",
+            parameters: {
+                required_approving_review_count: protect.required_approvals ?? 0,
+                dismiss_stale_reviews_on_push: false,
+                require_code_owner_review: false,
+                require_last_push_approval: false,
+                required_review_thread_resolution: false,
+            },
+        });
+    }
+    const checks = protect.required_checks ?? [];
+    if (checks.length > 0) {
+        rules.push({
+            type: "required_status_checks",
+            parameters: {
+                strict_required_status_checks_policy: false,
+                required_status_checks: checks.map((context) => ({ context })),
+            },
+        });
+    }
+    if (!(protect.allow_force_push ?? false))
+        rules.push({ type: "non_fast_forward" });
+    return rules;
+}
+const sameSummary = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+/** Reads the repository's current settings and lists what differs from `settings`. Reads only. */
+export async function planGithub(api, owner, name, settings) {
+    const repo = `${owner}/${name}`;
+    const base = `/repos/${owner}/${name}`;
+    const get = async (path, what, missingOk = false) => {
+        const response = await api.request("GET", `${base}${path}`);
+        return missingOk && response.status === 404 ? response : expect2xx(response, what, repo);
+    };
+    const send = async (method, path, what, body) => {
+        expect2xx(await api.request(method, `${base}${path}`, body), what, repo);
+    };
+    const changes = [];
+    const current = (await get("", `reading ${repo}`)).data;
+    for (const [key, field] of Object.entries(MERGE_FIELDS)) {
+        const want = settings.merge?.[key];
+        if (want === undefined || current[field] === want)
+            continue;
+        changes.push({
+            setting: `merge.${key}`,
+            from: show(current[field]),
+            to: show(want),
+            apply: () => send("PATCH", "", `setting merge.${key}`, { [field]: want }),
+        });
+    }
+    if (settings.description !== undefined && (current.description ?? "") !== settings.description) {
+        const description = settings.description;
+        changes.push({
+            setting: "description",
+            from: show(current.description),
+            to: show(description),
+            apply: () => send("PATCH", "", "setting the description", { description }),
+        });
+    }
+    if (settings.topics !== undefined) {
+        const have = ((await get("/topics", "reading topics")).data.names ?? []).slice().sort();
+        const want = [...settings.topics].sort();
+        if (JSON.stringify(have) !== JSON.stringify(want)) {
+            changes.push({
+                setting: "topics",
+                from: show(have),
+                to: show(want),
+                apply: () => send("PUT", "/topics", "setting topics", { names: want }),
+            });
+        }
+    }
+    const alerts = settings.security?.dependabot_alerts;
+    if (alerts !== undefined) {
+        const have = (await get("/vulnerability-alerts", "reading Dependabot alerts", true)).status === 204;
+        if (have !== alerts) {
+            changes.push({
+                setting: "security.dependabot_alerts",
+                from: show(have),
+                to: show(alerts),
+                apply: () => send(alerts ? "PUT" : "DELETE", "/vulnerability-alerts", "setting Dependabot alerts"),
+            });
+        }
+    }
+    const fixes = settings.security?.dependabot_security_updates;
+    if (fixes !== undefined) {
+        const response = await get("/automated-security-fixes", "reading Dependabot security updates", true);
+        const have = response.status !== 404 && response.data?.enabled === true;
+        if (have !== fixes) {
+            changes.push({
+                setting: "security.dependabot_security_updates",
+                from: show(have),
+                to: show(fixes),
+                apply: () => send(fixes ? "PUT" : "DELETE", "/automated-security-fixes", "setting Dependabot security updates"),
+            });
+        }
+    }
+    if (settings.protect !== undefined) {
+        const list = (await get("/rulesets?includes_parents=false", "reading rulesets")).data;
+        const existing = list.find((r) => r.name === RULESET_NAME);
+        const detail = existing
+            ? (await get(`/rulesets/${existing.id}`, "reading the repokeeper ruleset")).data
+            : null;
+        const have = detail ? summarize(detail.rules ?? []) : null;
+        if (settings.protect === false) {
+            if (existing) {
+                changes.push({
+                    setting: "protect",
+                    from: describeRules(have),
+                    to: "(none)",
+                    apply: () => send("DELETE", `/rulesets/${existing.id}`, "removing the repokeeper ruleset"),
+                });
+            }
+        }
+        else {
+            const rules = desiredRules(settings.protect);
+            const want = summarize(rules);
+            const targetsDefault = detail?.conditions?.ref_name?.include?.includes("~DEFAULT_BRANCH") ?? false;
+            const upToDate = have !== null && sameSummary(have, want) && detail?.enforcement === "active" && targetsDefault;
+            if (!upToDate) {
+                const body = {
+                    name: RULESET_NAME,
+                    target: "branch",
+                    enforcement: "active",
+                    conditions: { ref_name: { include: ["~DEFAULT_BRANCH"], exclude: [] } },
+                    rules,
+                };
+                changes.push({
+                    setting: "protect",
+                    from: describeRules(have),
+                    to: describeRules(want),
+                    apply: () => existing
+                        ? send("PUT", `/rulesets/${existing.id}`, "updating the repokeeper ruleset", body)
+                        : send("POST", "/rulesets", "creating the repokeeper ruleset", body),
+                });
+            }
+        }
+    }
+    return changes;
+}

package/dist/platforms/github.js

@@ -1,7 +1,7 @@
 import { stringify } from "yaml";
 import { defaultBranch } from "../config/types.js";
 import { MANAGED_HEADER } from "../model.js";
-import { REUSABLE_REPO, WORKFLOW_REF } from "../version.js";
+import { PACKAGE_VERSION, REUSABLE_REPO, WORKFLOW_REF } from "../version.js";
 const yamlFile = (module, path, data) => ({
     kind: "file",
     module,
@@ -120,6 +120,12 @@ export const githubPlatform = {
         if (ctx.config.modules.commits) {
             jobs.push(workflowKey("ci", path, ["jobs", "commits"], { uses: workflowRef(ctx, "commitlint.yml") }));
         }
+        if (ctx.config.modules.drift) {
+            jobs.push(workflowKey("ci", path, ["jobs", "repokeeper"], {
+                uses: workflowRef(ctx, "repokeeper-check.yml"),
+                with: { version: PACKAGE_VERSION },
+            }));
+        }
         if (jobs.length === 0)
             return [];
         return [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "repokeeper",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Keep every repository on one maintained standard: commits, git hooks, CI, releases, dependency updates and repo settings.",
   "type": "module",
   "bin": {