repokeeper 0.5.0 → 0.6.0

package/dist/commands/gitlab.js

@@ -0,0 +1,46 @@
+import { loadConfig } from "../config/load.js";
+import { UsageError } from "../errors.js";
+import { repoInfo } from "../git.js";
+import { gitlabRestApi, resolveGitlabToken } from "../gitlab/api.js";
+import { planGitlab } from "../gitlab/settings.js";
+/** `repokeeper gitlab apply`: diff the project's GitLab settings against `gitlab:` and apply on confirmation. */
+export async function gitlabApplyCommand(root, options, io) {
+    const config = await loadConfig(root);
+    if (config.platform !== "gitlab")
+        throw new UsageError(`this repository uses the ${config.platform} platform`);
+    const repo = await repoInfo(root, "gitlab");
+    if (!repo.owner)
+        throw new UsageError("the origin remote is not a GitLab project");
+    const path = `${repo.owner}/${repo.name}`;
+    const host = repo.host ?? "gitlab.com";
+    const api = io.gitlabApi ?? gitlabRestApi(await resolveGitlabToken(host), host);
+    // the jobs that wait for a secret: reported when it is missing, never created
+    const secrets = [
+        ...(config.modules.release ? [{ key: "GITLAB_TOKEN", job: "release" }] : []),
+        ...(config.modules.deps ? [{ key: "RENOVATE_TOKEN", job: "renovate" }] : []),
+    ];
+    const { changes, notes } = await planGitlab(api, path, config.gitlab ?? {}, secrets);
+    if (changes.length === 0)
+        io.out(`GitLab settings of ${path} match .repokeeper.yml`);
+    for (const change of changes)
+        io.out(`change     ${change.setting}: ${change.from} -> ${change.to}`);
+    for (const note of notes)
+        io.out(`note: ${note}`);
+    if (changes.length === 0)
+        return 0;
+    if (options.dryRun) {
+        io.out("dry run: nothing applied");
+        return 0;
+    }
+    const question = `apply ${changes.length} change(s) to ${path}?`;
+    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/commands/init.js

@@ -1,21 +1,23 @@
 import { existsSync } from "node:fs";
-import { writeFile } from "node:fs/promises";
+import { readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { CONFIG_FILE, loadConfig, renderConfig } from "../config/load.js";
+import { CONFIG_FILE, loadConfig, renderConfig, setStandard } from "../config/load.js";
 import { defaultConfig } from "../config/types.js";
 import { UsageError } from "../errors.js";
 import { dirtyPaths, gitUserName, remoteDefaultBranch, remoteHost, repoInfo } from "../git.js";
 import { outputId } from "../model.js";
 import { planOutputs } from "../plan.js";
 import { platformFor } from "../platforms/index.js";
-import { detectStacks } from "../stacks/index.js";
+import { detectStackLayout } from "../stacks/index.js";
 import { applySync } from "../sync/apply.js";
 import { hashText } from "../sync/hash.js";
-import { targetOf, writeLock } from "../sync/lock.js";
+import { readLock, targetOf, writeLock } from "../sync/lock.js";
 import { readCurrent } from "../sync/state.js";
 import { computeSync, pathsToWrite } from "../sync/sync.js";
 import { STANDARD_VERSION } from "../version.js";
+import { assertSupportedStandard } from "./check.js";
 import { buildContext } from "./context.js";
+import { applyPreset, chooseModules } from "./presets.js";
 import { nextSteps, printResult, printWarnings } from "./report.js";
 /** A dirty path is still safe to write when every part repokeeper manages in it is exactly what it last wrote. */
 async function onlyRepokeeperChanges(root, path, lock) {
@@ -49,15 +51,33 @@ export async function initCommand(root, options, io) {
     if (options.relock)
         return relock(root, options, io);
     if (existsSync(join(root, CONFIG_FILE))) {
-        throw new UsageError(`${CONFIG_FILE} already exists; run \`repokeeper update\` or \`repokeeper check\``);
+        // a lock means the standard was applied here before; without one the file was written by hand
+        if ((await readLock(root)) !== null) {
+            throw new UsageError(`${CONFIG_FILE} already exists; run \`repokeeper update\` or \`repokeeper check\``);
+        }
+        return initFromConfig(root, options, io);
     }
-    const stacks = options.stacks.length > 0 ? options.stacks : await detectStacks(root);
+    const layout = options.stacks.length > 0
+        ? { stacks: options.stacks, directories: options.stackDirectories ?? {}, skipped: [] }
+        : await detectStackLayout(root);
+    const { stacks } = layout;
     if (stacks.length === 0)
         throw new UsageError("no supported stack detected; pass --stack node");
+    for (const id of stacks) {
+        if (layout.directories[id] !== undefined)
+            io.out(`found ${id} in ${layout.directories[id]}/`);
+    }
+    for (const { stack, directory } of layout.skipped) {
+        io.out(`note: ${directory}/ also holds a ${stack} project; one folder per stack is managed, so it is left out`);
+    }
     const platform = options.platform ?? ((await remoteHost(root))?.includes("gitlab") ? "gitlab" : "github");
     const repo = await repoInfo(root, platform);
     const holder = (await gitUserName(root)) ?? repo.owner ?? "the project authors";
-    const config = defaultConfig({
+    const { confirm } = io;
+    if (options.interactive && confirm === undefined) {
+        throw new UsageError("--interactive needs a terminal to ask its questions in");
+    }
+    const defaults = defaultConfig({
         stacks,
         standard: STANDARD_VERSION,
         copyright: `${new Date().getFullYear()} ${holder}`,
@@ -65,12 +85,29 @@ export async function initCommand(root, options, io) {
         codeowners: repo.owner ? [`@${repo.owner}`] : [],
         platform,
     });
+    for (const id of stacks) {
+        const directory = layout.directories[id];
+        if (directory !== undefined)
+            defaults.stack_options[id] = { directory };
+    }
     const branch = await remoteDefaultBranch(root);
     if (branch && branch !== "main")
-        config[platform] = { default_branch: branch };
-    const ctx = await buildContext(root, config, repo);
+        defaults[platform] = { default_branch: branch };
+    const preset = options.preset ?? "standard";
+    let config = applyPreset(defaults, preset);
+    const plan = async (candidate) => {
+        const ctx = await buildContext(root, candidate, repo);
+        return { ctx, outputs: planOutputs(ctx) };
+    };
+    if (options.interactive && confirm !== undefined) {
+        // the default health settings stay at hand for a preset that left the module out
+        const health = defaults.modules.health;
+        if (health)
+            config = await chooseModules(config, health, plan, { ...io, confirm });
+    }
+    const { ctx, outputs } = await plan(config);
     const adopt = options.adoptAll ? "all" : new Set(options.adopt);
-    const result = await computeSync(root, planOutputs(ctx), null, { adopt, accept: new Set() });
+    const result = await computeSync(root, outputs, null, { adopt, accept: new Set() });
     if (!options.dryRun)
         await guardUncommitted(root, result, options.force);
     printResult(io, result);
@@ -78,12 +115,69 @@ export async function initCommand(root, options, io) {
         io.out("dry run: nothing written");
         return 0;
     }
+    if (options.interactive && confirm !== undefined && !(await confirm("Write these files?", true))) {
+        io.out("nothing written");
+        return 0;
+    }
     await writeFile(join(root, CONFIG_FILE), renderConfig(config));
     await applySync(root, result, null, STANDARD_VERSION);
     io.out(`applied standard ${STANDARD_VERSION}; wrote ${CONFIG_FILE}`);
     await printWarnings(root, ctx, io);
     for (const step of await nextSteps(root, ctx, result))
         io.out(`next: ${step}`);
+    if (config.github?.protect || config.github?.security) {
+        io.out("next: run `repokeeper github apply` to put the branch protection and security settings in place");
+    }
+    io.out(`next: commit with "chore(repokeeper): apply standard ${STANDARD_VERSION}"`);
+    return 0;
+}
+/**
+ * Applies a `.repokeeper.yml` that was written before repokeeper ran here, by hand or by the
+ * playground: nothing is detected or asked, the file says it all.
+ */
+async function initFromConfig(root, options, io) {
+    const given = [
+        options.stacks.length > 0 ? "--stack" : undefined,
+        options.platform !== undefined ? "--platform" : undefined,
+        options.preset !== undefined ? "--preset" : undefined,
+    ].filter((name) => name !== undefined);
+    if (given.length > 0) {
+        throw new UsageError(`${CONFIG_FILE} already exists and is applied as it is written; leave out ${given.join(", ")}, or remove the file`);
+    }
+    const { confirm } = io;
+    if (options.interactive && confirm === undefined) {
+        throw new UsageError("--interactive needs a terminal to ask its questions in");
+    }
+    const config = await loadConfig(root);
+    assertSupportedStandard(config.standard);
+    io.out(`using the ${CONFIG_FILE} that is already here`);
+    const ctx = await buildContext(root, { ...config, standard: STANDARD_VERSION });
+    const adopt = options.adoptAll ? "all" : new Set(options.adopt);
+    const result = await computeSync(root, planOutputs(ctx), null, { adopt, accept: new Set() });
+    if (!options.dryRun)
+        await guardUncommitted(root, result, options.force);
+    printResult(io, result);
+    if (options.dryRun) {
+        io.out("dry run: nothing written");
+        return 0;
+    }
+    // the module questions of a detected init have their answers in the file already
+    if (options.interactive && confirm !== undefined && !(await confirm("Write these files?", true))) {
+        io.out("nothing written");
+        return 0;
+    }
+    if (config.standard !== STANDARD_VERSION) {
+        const path = join(root, CONFIG_FILE);
+        await writeFile(path, setStandard(await readFile(path, "utf8"), STANDARD_VERSION));
+    }
+    await applySync(root, result, null, STANDARD_VERSION);
+    io.out(`applied standard ${STANDARD_VERSION}`);
+    await printWarnings(root, ctx, io);
+    for (const step of await nextSteps(root, ctx, result))
+        io.out(`next: ${step}`);
+    if (config.github?.protect || config.github?.security) {
+        io.out("next: run `repokeeper github apply` to put the branch protection and security settings in place");
+    }
     io.out(`next: commit with "chore(repokeeper): apply standard ${STANDARD_VERSION}"`);
     return 0;
 }

package/dist/commands/presets.js

@@ -0,0 +1,114 @@
+export const PRESETS = ["essential", "standard", "strict"];
+/** One line per preset, for the usage text and the interactive question. */
+export const PRESET_SUMMARY = {
+    essential: "editor settings, .gitignore and CI only",
+    standard: "everything except the drift check (the default)",
+    strict: "everything, the drift check, and branch protection with a required review",
+};
+/** The order the modules are offered in: files first, then the automation built on them. */
+export const MODULE_IDS = [
+    "editorconfig",
+    "gitignore",
+    "commits",
+    "hooks",
+    "ci",
+    "release",
+    "deps",
+    "health",
+    "drift",
+];
+/**
+ * Applies a preset to a freshly built default configuration.
+ *
+ * A preset only switches on what repokeeper really does. There is no tier that promises code or
+ * secret scanning, because no module writes it.
+ */
+export function applyPreset(config, preset) {
+    if (preset === "standard")
+        return config;
+    if (preset === "essential") {
+        return {
+            ...config,
+            modules: {
+                ...config.modules,
+                commits: false,
+                hooks: false,
+                release: false,
+                deps: false,
+                drift: false,
+                health: false,
+            },
+        };
+    }
+    const strict = { ...config, modules: { ...config.modules, drift: true } };
+    // repository settings exist on GitHub only; they take effect with `repokeeper github apply`
+    if (config.platform === "github") {
+        strict.github = {
+            ...config.github,
+            security: { dependabot_alerts: true, dependabot_security_updates: true },
+            protect: {
+                require_pull_request: true,
+                required_approvals: 1,
+                allow_force_push: false,
+                ...(config.modules.commits ? { required_checks: ["commits / commitlint"] } : {}),
+            },
+        };
+    }
+    return strict;
+}
+/** The files each module would write to, so a question about it can name them. */
+function filesByModule(outputs) {
+    const files = new Map();
+    for (const output of outputs) {
+        // one line per file, however many of its keys or blocks the module manages
+        files.set(output.module, (files.get(output.module) ?? new Set()).add(output.path));
+    }
+    return new Map([...files].map(([module, paths]) => [module, [...paths].sort()]));
+}
+/** The drift check is a job of the CI workflow, planned by the ci module. */
+const plannedBy = (module) => (module === "drift" ? "ci" : module);
+/**
+ * Asks, module by module, whether to apply it, naming the files it would write. The answer that
+ * Enter gives is the preset's.
+ *
+ * @param plan Plans the outputs for a configuration; called with every module switched on, so that
+ *   a module the preset leaves out can still say what it would add.
+ */
+export async function chooseModules(config, health, plan, io) {
+    const everything = {
+        ...config,
+        modules: {
+            editorconfig: true,
+            commits: true,
+            hooks: true,
+            ci: true,
+            release: true,
+            deps: true,
+            gitignore: true,
+            drift: true,
+            health,
+        },
+    };
+    const files = filesByModule((await plan(everything)).outputs);
+    const modules = { ...config.modules };
+    io.out("Choose what to apply. Enter keeps the answer in capitals.");
+    for (const id of MODULE_IDS) {
+        const listed = id === "drift"
+            ? [".github/workflows/ci.yml (a job that fails a pull request when a managed file was edited by hand)"]
+            : (files.get(plannedBy(id)) ?? []);
+        if (listed.length === 0)
+            continue;
+        const shown = listed.length > 6 ? [...listed.slice(0, 6), `and ${listed.length - 6} more`] : listed;
+        io.out("");
+        io.out(`${id}:`);
+        for (const file of shown)
+            io.out(`  ${file}`);
+        const wanted = await io.confirm(`Apply ${id}?`, Boolean(modules[id]));
+        if (id === "health")
+            modules.health = wanted ? health : false;
+        else
+            modules[id] = wanted;
+    }
+    io.out("");
+    return { ...config, modules };
+}

package/dist/commands/report.js

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { parse } from "yaml";
 import { duplicateTestRuns } from "../duplicates.js";
 import { crlfTrackedFiles } from "../git.js";
-import { describeOutput } from "../model.js";
+import { describeOutput, nodeAtRoot } from "../model.js";
 import { overriddenAttributes } from "../sync/attributes.js";
 import { TOOL_VERSIONS } from "../version.js";
 /** How to name the output under `owned`: the path, or `path#key` for one key of a shared file. */
@@ -47,7 +47,7 @@ export async function nextSteps(root, ctx, result) {
     const steps = [];
     const wrote = (path) => result.decisions.some((d) => d.output.path === path && WROTE.includes(d.action));
     if (ctx.config.modules.hooks && wrote("lefthook.yml")) {
-        steps.push(ctx.stacks.some((s) => s.id === "node")
+        steps.push(nodeAtRoot(ctx.stacks)
             ? "install dependencies; this installs the git hooks"
             : `run \`npx --yes lefthook@${TOOL_VERSIONS.lefthook} install\` to enable the git hooks`);
     }

package/dist/commands/update.js

@@ -11,8 +11,8 @@ import { assertSupportedStandard } from "./check.js";
 import { buildContext } from "./context.js";
 import { guardUncommitted } from "./init.js";
 import { nextSteps, printResult, printWarnings } from "./report.js";
-export async function updateCommand(root, options, io) {
-    const config = await loadConfig(root);
+export async function updateCommand(root, options, io, change) {
+    const config = change?.config ?? (await loadConfig(root));
     assertSupportedStandard(config.standard);
     const lock = await readLock(root);
     if (!lock)
@@ -31,6 +31,7 @@ export async function updateCommand(root, options, io) {
         io.out("dry run: nothing written");
         return 0;
     }
+    await change?.beforeWrite();
     await applySync(root, result, lock, STANDARD_VERSION);
     const steps = await nextSteps(root, ctx, result);
     await printWarnings(root, ctx, io);

package/dist/config/schema.js

@@ -1,5 +1,7 @@
+import { ACCESS_LEVELS } from "../gitlab/settings.js";
 import { STACK_IDS } from "./types.js";
 const flag = { type: "boolean" };
+const ACCESS = Object.keys(ACCESS_LEVELS);
 export const configSchema = {
     type: "object",
     additionalProperties: false,
@@ -46,6 +48,16 @@ export const configSchema = {
             additionalProperties: false,
             properties: {
                 default_branch: { type: "string", minLength: 1 },
+                workflows: {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: {
+                        // "local", or the owner/name of a repository holding a copy of the reusable workflows
+                        source: { type: "string", pattern: "^(local|[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+)$" },
+                        // "exact", or a tag, branch or commit SHA
+                        ref: { type: "string", pattern: "^[A-Za-z0-9_./-]+$" },
+                    },
+                },
                 description: { type: "string" },
                 topics: { type: "array", uniqueItems: true, items: { type: "string", pattern: "^[a-z0-9][a-z0-9-]{0,49}$" } },
                 merge: {
@@ -78,7 +90,34 @@ export const configSchema = {
         gitlab: {
             type: "object",
             additionalProperties: false,
-            properties: { default_branch: { type: "string", minLength: 1 } },
+            properties: {
+                default_branch: { type: "string", minLength: 1 },
+                description: { type: "string" },
+                topics: { type: "array", uniqueItems: true, items: { type: "string", minLength: 1 } },
+                merge: {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: {
+                        method: { enum: ["merge", "rebase_merge", "ff"] },
+                        squash: { enum: ["never", "always", "default_on", "default_off"] },
+                        delete_source_branch: flag,
+                        pipeline_must_succeed: flag,
+                        discussions_must_be_resolved: flag,
+                    },
+                },
+                protect: {
+                    anyOf: [
+                        { const: false },
+                        {
+                            type: "object",
+                            additionalProperties: false,
+                            properties: { push: { enum: ACCESS }, merge: { enum: ACCESS }, allow_force_push: flag },
+                        },
+                    ],
+                },
+                // five cron fields, read in UTC; false removes the schedule repokeeper made
+                renovate_schedule: { anyOf: [{ const: false }, { type: "string", pattern: "^\\S+( \\S+){4}$" }] },
+            },
         },
     },
 };

package/dist/duplicates.js

@@ -1,11 +1,11 @@
 import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { parse } from "yaml";
-import { REUSABLE_REPO } from "./version.js";
 const WORKFLOWS = ".github/workflows";
 const calls = (job) => {
     const uses = job?.uses;
-    return (typeof uses === "string" && (uses.startsWith(`${REUSABLE_REPO}/`) || uses.startsWith("./.github/workflows/stack-")));
+    // a stack workflow, wherever it is called from: repokeeper's repository, a copy of it, or this repository
+    return typeof uses === "string" && /(^\.|^[^/]+\/[^/]+)\/\.github\/workflows\/stack-[a-z]+\.yml(@|$)/.test(uses);
 };
 /** Workflows of the user's own that run a stack's test command, which repokeeper's ci job now runs as well. */
 export async function duplicateTestRuns(root, stacks) {

package/dist/errors.js

@@ -18,7 +18,7 @@ export class UsageError extends RepokeeperError {
         super(message, 2);
     }
 }
-/** A GitHub API call failed; nothing on disk was touched. */
+/** A GitHub or GitLab API call failed; nothing on disk was touched. */
 export class ApiError extends RepokeeperError {
     constructor(message) {
         super(message, 3);

package/dist/gitlab/api.js

@@ -0,0 +1,50 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { ApiError } from "../errors.js";
+const execFileAsync = promisify(execFile);
+/** `GITLAB_TOKEN`, or the token the GitLab CLI holds for the host. */
+export async function resolveGitlabToken(host, env = process.env) {
+    if (env.GITLAB_TOKEN)
+        return env.GITLAB_TOKEN;
+    try {
+        const { stdout } = await execFileAsync("glab", ["config", "get", "token", "--host", host], { encoding: "utf8" });
+        if (stdout.trim())
+            return stdout.trim();
+    }
+    catch {
+        // fall through to the error below
+    }
+    throw new ApiError(`no GitLab token for ${host}: set GITLAB_TOKEN or sign in with \`glab auth login\``);
+}
+export function gitlabRestApi(token, host) {
+    const base = `https://${host}/api/v4`;
+    return {
+        async request(method, path, body) {
+            let response;
+            try {
+                response = await fetch(`${base}${path}`, {
+                    method,
+                    headers: {
+                        accept: "application/json",
+                        // read as a personal, project or group access token, and as the OAuth token of `glab`
+                        authorization: `Bearer ${token}`,
+                        ...(body === undefined ? {} : { "content-type": "application/json" }),
+                    },
+                    body: body === undefined ? undefined : JSON.stringify(body),
+                });
+            }
+            catch (error) {
+                throw new ApiError(`GitLab 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 };
+        },
+    };
+}