repokeeper 0.5.0 → 0.6.0

package/dist/gitlab/settings.js

@@ -0,0 +1,181 @@
+import { ApiError } from "../errors.js";
+export const ACCESS_LEVELS = { none: 0, developers: 30, maintainers: 40 };
+/** Description of the pipeline schedule repokeeper owns; a schedule under another name is never touched. */
+export const RENOVATE_SCHEDULE = "repokeeper: renovate";
+const MERGE_FIELDS = {
+    method: "merge_method",
+    squash: "squash_option",
+    delete_source_branch: "remove_source_branch_after_merge",
+    pipeline_must_succeed: "only_allow_merge_if_pipeline_succeeds",
+    discussions_must_be_resolved: "only_allow_merge_if_all_discussions_are_resolved",
+};
+function expect2xx(response, what, project) {
+    if (response.status < 400)
+        return response;
+    const data = response.data;
+    const said = data?.message ?? data?.error;
+    const message = typeof said === "string" ? said : said ? JSON.stringify(said) : `HTTP ${response.status}`;
+    const access = response.status === 401 || response.status === 403 || response.status === 404
+        ? `; this needs the Maintainer role on ${project} and a token with the api scope`
+        : "";
+    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 levels = (list) => (list ?? []).map((entry) => entry.access_level ?? -1).sort((a, b) => a - b);
+const levelName = (level) => Object.entries(ACCESS_LEVELS).find(([, value]) => value === level)?.[0] ??
+    // a user, a group or a deploy key allowed by name (paid tiers), or a level repokeeper has no word for
+    (level === -1 ? "named members" : `level ${level}`);
+const describeLevels = (list) => (list.length === 0 ? "none" : list.map(levelName).join(" + "));
+function describeProtection(protection) {
+    if (protection === null)
+        return "(not protected)";
+    return [
+        `push: ${describeLevels(protection.push)}`,
+        `merge: ${describeLevels(protection.merge)}`,
+        protection.forcePush ? "force push allowed" : "no force push",
+    ].join("; ");
+}
+const branchOf = (ref) => ref.replace(/^refs\/heads\//, "");
+const describeSchedule = (schedule) => schedule === undefined
+    ? "(none)"
+    : `${schedule.cron} on ${branchOf(schedule.ref)}${schedule.active ? "" : " (inactive)"}`;
+/**
+ * Reads the project's current settings and lists what differs from `settings`. Reads only.
+ *
+ * @param secrets CI/CD variables the generated jobs wait for; a missing one is reported, never created.
+ */
+export async function planGitlab(api, path, settings, secrets = []) {
+    const base = `/projects/${encodeURIComponent(path)}`;
+    const get = async (suffix, what, missingOk = false) => {
+        const response = await api.request("GET", `${base}${suffix}`);
+        return missingOk && response.status === 404 ? response : expect2xx(response, what, path);
+    };
+    const send = async (method, suffix, what, body) => {
+        expect2xx(await api.request(method, `${base}${suffix}`, body), what, path);
+    };
+    const changes = [];
+    const current = (await get("", `reading ${path}`)).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("PUT", "", `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("PUT", "", "setting the description", { description }),
+        });
+    }
+    if (settings.topics !== undefined) {
+        const have = (current.topics ?? []).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", "", "setting topics", { topics: want }),
+            });
+        }
+    }
+    const branch = settings.default_branch ?? current.default_branch ?? "main";
+    if (settings.protect !== undefined) {
+        const rule = `/protected_branches/${encodeURIComponent(branch)}`;
+        const response = await get(rule, `reading the protection of ${branch}`, true);
+        const existing = response.status === 404 ? null : response.data;
+        const have = existing && {
+            push: levels(existing.push_access_levels),
+            merge: levels(existing.merge_access_levels),
+            forcePush: existing.allow_force_push === true,
+        };
+        if (settings.protect === false) {
+            if (have) {
+                changes.push({
+                    setting: `protect ${branch}`,
+                    from: describeProtection(have),
+                    to: describeProtection(null),
+                    apply: () => send("DELETE", rule, `removing the protection of ${branch}`),
+                });
+            }
+        }
+        else {
+            const want = {
+                push: [ACCESS_LEVELS[settings.protect.push ?? "maintainers"]],
+                merge: [ACCESS_LEVELS[settings.protect.merge ?? "maintainers"]],
+                forcePush: settings.protect.allow_force_push ?? false,
+            };
+            if (JSON.stringify(have) !== JSON.stringify(want)) {
+                changes.push({
+                    setting: `protect ${branch}`,
+                    from: describeProtection(have),
+                    to: describeProtection(want),
+                    // a protection is replaced as a whole: changing its access levels in place needs the id of each one
+                    apply: async () => {
+                        if (have)
+                            await send("DELETE", rule, `removing the protection of ${branch}`);
+                        await send("POST", "/protected_branches", `protecting ${branch}`, {
+                            name: branch,
+                            push_access_level: want.push[0],
+                            merge_access_level: want.merge[0],
+                            allow_force_push: want.forcePush,
+                        });
+                    },
+                });
+            }
+        }
+    }
+    if (settings.renovate_schedule !== undefined) {
+        const list = (await get("/pipeline_schedules", "reading the pipeline schedules")).data;
+        const existing = list.find((schedule) => schedule.description === RENOVATE_SCHEDULE);
+        const cron = settings.renovate_schedule;
+        if (cron === false) {
+            if (existing) {
+                changes.push({
+                    setting: "renovate_schedule",
+                    from: describeSchedule(existing),
+                    to: describeSchedule(undefined),
+                    apply: () => send("DELETE", `/pipeline_schedules/${existing.id}`, "removing the renovate schedule"),
+                });
+            }
+        }
+        else if (!existing || existing.cron !== cron || branchOf(existing.ref) !== branch || !existing.active) {
+            const want = { cron, ref: branch, active: true };
+            changes.push({
+                setting: "renovate_schedule",
+                from: describeSchedule(existing),
+                to: describeSchedule(want),
+                apply: () => existing
+                    ? send("PUT", `/pipeline_schedules/${existing.id}`, "updating the renovate schedule", want)
+                    : send("POST", "/pipeline_schedules", "creating the renovate schedule", {
+                        description: RENOVATE_SCHEDULE,
+                        cron_timezone: "UTC",
+                        ...want,
+                    }),
+            });
+        }
+    }
+    const notes = [];
+    for (const { key, job } of secrets) {
+        const response = await api.request("GET", `${base}/variables/${key}`);
+        if (response.status === 404) {
+            notes.push(`no CI/CD variable ${key} in ${path}: the ${job} job stays inactive until one is set, here or in a group above`);
+        }
+        else if (response.status >= 400) {
+            notes.push(`could not read the CI/CD variables of ${path} (HTTP ${response.status}); ${key} was not checked`);
+        }
+    }
+    return { changes, notes };
+}

package/dist/model.js

@@ -23,3 +23,11 @@ export function describeOutput(output) {
         return `${output.path} (block ${output.id})`;
     return `${output.path} (${output.keyPath.join(".")})`;
 }
+/** `command`, run from the stack's folder when it has one. */
+export function inDirectory(stack, command) {
+    return stack.directory ? `cd ${stack.directory} && ${command}` : command;
+}
+/** Whether the Node.js project is the repository itself, so its package.json can carry repokeeper's tools. */
+export function nodeAtRoot(stacks) {
+    return stacks.some((stack) => stack.id === "node" && !stack.directory);
+}

package/dist/modules/commits.js

@@ -1,4 +1,4 @@
-import { MANAGED_HEADER } from "../model.js";
+import { MANAGED_HEADER, nodeAtRoot } from "../model.js";
 import { TOOL_VERSIONS } from "../version.js";
 const COMMITLINT_CONFIG = `// ${MANAGED_HEADER}
 export default {
@@ -15,7 +15,8 @@ export const commitsModule = {
         const outputs = [
             { kind: "file", module: "commits", path: "commitlint.config.mjs", content: COMMITLINT_CONFIG },
         ];
-        if (ctx.stacks.some((s) => s.id === "node")) {
+        // a package.json in a folder of its own is the project's, not the place for the repository's tools
+        if (nodeAtRoot(ctx.stacks)) {
             outputs.push({
                 kind: "json",
                 module: "commits",

package/dist/modules/deps.js

@@ -1,5 +1,5 @@
 export const depsModule = {
     id: "deps",
     enabled: (config) => config.modules.deps,
-    outputs: (ctx) => ctx.platform.dependencyUpdates(ctx.stacks.flatMap((s) => s.dependabot)),
+    outputs: (ctx) => ctx.platform.dependencyUpdates(ctx.stacks.flatMap((stack) => stack.dependabot.map((ecosystem) => ({ ecosystem, directory: stack.directory ? `/${stack.directory}` : "/" }))), ctx),
 };

package/dist/modules/health.js

@@ -1,6 +1,6 @@
 import { defaultBranch } from "../config/types.js";
 import { UsageError } from "../errors.js";
-import { MANAGED_HEADER } from "../model.js";
+import { inDirectory, MANAGED_HEADER, nodeAtRoot } from "../model.js";
 import { readTemplate } from "../templates.js";
 import { TOOL_VERSIONS } from "../version.js";
 const MIT = (holder) => `MIT License
@@ -42,9 +42,9 @@ export const healthModule = {
         }
         const report = ctx.platform.securityReport(ctx.repo);
         outputs.push(md("SECURITY.md", `# Security Policy\n\n<!-- ${MANAGED_HEADER} -->\n\n## Supported versions\n\nSecurity fixes are released for the latest published version.\n\n## Reporting a vulnerability\n\nPlease do not open a public issue. Report the vulnerability privately ${report}.\nThe maintainers will acknowledge it as soon as possible and keep you informed until it is resolved.\n`));
-        const install = ctx.stacks.map((s) => s.install).filter((c) => c !== null);
+        const install = ctx.stacks.flatMap((s) => (s.install === null ? [] : [inDirectory(s, s.install)]));
         const run = install.length ? `Run ${install.map((c) => `\`${c}\``).join(" and ")}.` : "";
-        const hooks = ctx.stacks.some((s) => s.id === "node")
+        const hooks = nodeAtRoot(ctx.stacks)
             ? "Installing the dependencies also installs the git hooks (lefthook)."
             : `${run ? "Then run" : "Run"} \`npx --yes lefthook@${TOOL_VERSIONS.lefthook} install\` once to enable the git hooks (they need Node.js 22 or newer).`;
         const setup = [run, hooks].filter(Boolean).join(" ");

package/dist/modules/hooks.js

@@ -1,22 +1,24 @@
 import { stringify } from "yaml";
-import { MANAGED_HEADER } from "../model.js";
+import { MANAGED_HEADER, nodeAtRoot } from "../model.js";
 import { TOOL_VERSIONS } from "../version.js";
+/** lefthook runs a job from `root` and hands it only the staged files under it. */
+const rootOf = (stack) => (stack.directory ? { root: `${stack.directory}/` } : {});
 export const hooksModule = {
     id: "hooks",
     enabled: (config) => config.modules.hooks,
     outputs(ctx) {
         const config = {};
-        const preCommit = ctx.stacks.flatMap((s) => s.staged).map((job) => ({ ...job, stage_fixed: true }));
+        const preCommit = ctx.stacks.flatMap((s) => s.staged.map((job) => ({ ...job, ...rootOf(s), stage_fixed: true })));
         if (preCommit.length > 0)
             config["pre-commit"] = { parallel: true, jobs: preCommit };
         if (ctx.config.modules.commits) {
-            const node = ctx.stacks.some((s) => s.id === "node");
+            const node = nodeAtRoot(ctx.stacks);
             const commitlint = node
                 ? "npx --no-install commitlint --edit {1}"
                 : `npx --yes --package @commitlint/cli@${TOOL_VERSIONS.commitlintCli} --package @commitlint/config-conventional@${TOOL_VERSIONS.commitlintConventional} -- commitlint --edit {1}`;
             config["commit-msg"] = { jobs: [{ name: "commitlint", run: commitlint }] };
         }
-        const prePush = ctx.stacks.flatMap((s) => (s.test ? [{ name: `${s.id}:test`, run: s.test }] : []));
+        const prePush = ctx.stacks.flatMap((s) => (s.test ? [{ name: `${s.id}:test`, run: s.test, ...rootOf(s) }] : []));
         if (prePush.length > 0)
             config["pre-push"] = { jobs: prePush };
         const outputs = [
@@ -27,7 +29,7 @@ export const hooksModule = {
                 content: `# ${MANAGED_HEADER}\n${stringify(config, { lineWidth: 0 })}`,
             },
         ];
-        if (ctx.stacks.some((s) => s.id === "node")) {
+        if (nodeAtRoot(ctx.stacks)) {
             outputs.push({
                 kind: "json",
                 module: "hooks",

package/dist/modules/release.js

@@ -1,16 +1,29 @@
 /** One release per repository: the first stack with a language release type wins, otherwise the first stack's `simple` release (which may name extra files). */
+export function pickReleaseStack(stacks) {
+    return stacks.find((stack) => stack.release.type !== "simple") ?? stacks[0];
+}
 export function pickRelease(stacks) {
-    const language = stacks.find((stack) => stack.release.type !== "simple");
-    return language?.release ?? stacks[0]?.release ?? { type: "simple", version: null };
+    return pickReleaseStack(stacks)?.release ?? { type: "simple", version: null };
 }
 export const releaseModule = {
     id: "release",
     enabled: (config) => config.modules.release,
     outputs: (ctx) => {
-        const release = pickRelease(ctx.stacks);
+        const stack = pickReleaseStack(ctx.stacks);
+        const release = stack?.release ?? { type: "simple", version: null };
+        const directory = stack?.directory;
+        // the markers go into a file of the repository, so its path starts at the root
+        const markerPath = (path) => (directory ? `${directory}/${path}` : path);
         const markers = release.versionLine
-            ? [{ kind: "marker", module: "release", path: release.versionLine.path, line: release.versionLine.line }]
+            ? [
+                {
+                    kind: "marker",
+                    module: "release",
+                    path: markerPath(release.versionLine.path),
+                    line: release.versionLine.line,
+                },
+            ]
             : [];
-        return [...ctx.platform.releaseAutomation(ctx, release), ...markers];
+        return [...ctx.platform.releaseAutomation(ctx, release, directory), ...markers];
     },
 };

package/dist/platforms/github.js

@@ -1,7 +1,10 @@
 import { stringify } from "yaml";
+import { CONFIG_FILE } from "../config/load.js";
 import { defaultBranch, STACK_IDS } from "../config/types.js";
-import { MANAGED_HEADER } from "../model.js";
-import { PACKAGE_VERSION, REUSABLE_REPO, WORKFLOW_REF } from "../version.js";
+import { ConfigError } from "../errors.js";
+import { MANAGED_HEADER, } from "../model.js";
+import { readWorkflow } from "../templates.js";
+import { EXACT_WORKFLOW_REF, PACKAGE_VERSION, REUSABLE_REPO, WORKFLOW_REF } from "../version.js";
 const yamlFile = (module, path, data) => ({
     kind: "file",
     module,
@@ -9,10 +12,47 @@ const yamlFile = (module, path, data) => ({
     content: `# ${MANAGED_HEADER}\n${stringify(data)}`,
 });
 const WORKFLOW_KEYS = ["name", "on", "permissions", "concurrency", "env", "defaults", "jobs"];
-/** Reference to a reusable workflow; local inside the repository that hosts them. */
+function workflowOrigin(ctx) {
+    // the repository that hosts the workflows calls its own files
+    if (ctx.repo.owner !== null && `${ctx.repo.owner}/${ctx.repo.name}` === REUSABLE_REPO)
+        return { local: true, self: true };
+    const { source, ref } = ctx.config.github?.workflows ?? {};
+    if (source === "local")
+        return { local: true, self: false };
+    const repo = source ?? REUSABLE_REPO;
+    if (ref === "exact") {
+        if (repo !== REUSABLE_REPO) {
+            throw new ConfigError(`${CONFIG_FILE}: github.workflows.ref: exact follows repokeeper's own releases; for ${repo}, name a tag, a branch or a commit`);
+        }
+        return { local: false, repo, ref: EXACT_WORKFLOW_REF, pinned: true };
+    }
+    // a copy in a repository of your own has no release tags of repokeeper's to follow
+    return {
+        local: false,
+        repo,
+        ref: ref ?? (repo === REUSABLE_REPO ? WORKFLOW_REF : "main"),
+        pinned: ref !== undefined,
+    };
+}
+/** Reference to a reusable workflow, as the `uses` of a caller job. */
 function workflowRef(ctx, file) {
-    const self = ctx.repo.owner !== null && `${ctx.repo.owner}/${ctx.repo.name}` === REUSABLE_REPO;
-    return self ? `./.github/workflows/${file}` : `${REUSABLE_REPO}/.github/workflows/${file}@${WORKFLOW_REF}`;
+    const origin = workflowOrigin(ctx);
+    return origin.local ? `./.github/workflows/${file}` : `${origin.repo}/.github/workflows/${file}@${origin.ref}`;
+}
+/**
+ * The reusable workflows themselves, for a repository that keeps its own copies. Seeds: written
+ * once and from then on the repository's, so its owners decide when a copy changes.
+ */
+function localWorkflows(ctx, module, files) {
+    const origin = workflowOrigin(ctx);
+    if (!origin.local || origin.self)
+        return [];
+    return [...new Set(files)].map((file) => ({
+        kind: "seed",
+        module,
+        path: `.github/workflows/${file}`,
+        content: `# Copied from repokeeper ${PACKAGE_VERSION} (https://github.com/${REUSABLE_REPO}). This copy is yours: repokeeper does not update it.\n${readWorkflow(file)}`,
+    }));
 }
 const workflowKey = (module, path, keyPath, value) => ({
     kind: "yaml",
@@ -122,10 +162,18 @@ export const githubPlatform = {
         }
         return outputs;
     },
-    dependencyUpdates(ecosystems) {
-        const updates = [...new Set([...ecosystems, "github-actions"])].map((ecosystem) => ({
+    dependencyUpdates(requested, ctx) {
+        // a pinned reference is moved by `repokeeper update` or by its owner in .repokeeper.yml; a
+        // Dependabot bump of it would edit a key repokeeper manages and show up as drift every time
+        const origin = workflowOrigin(ctx);
+        const pinnedWorkflows = !origin.local && origin.pinned ? [{ "dependency-name": `${origin.repo}*` }] : [];
+        // workflows always live at the root, whatever folders the stacks are in
+        const all = [...requested, { ecosystem: "github-actions", directory: "/" }];
+        const unique = all.filter((update, index) => all.findIndex((other) => other.ecosystem === update.ecosystem && other.directory === update.directory) ===
+            index);
+        const updates = unique.map(({ ecosystem, directory }) => ({
             "package-ecosystem": ecosystem,
-            directory: "/",
+            directory,
             schedule: { interval: "weekly" },
             groups: { [`${ecosystem}-minor-and-patch`]: { "update-types": ["minor", "patch"] } },
             // Dependabot infers a Conventional Commits prefix only from history; young repositories fail commitlint
@@ -134,6 +182,7 @@ export const githubPlatform = {
             ...(ecosystem === "npm"
                 ? { ignore: [{ "dependency-name": "@types/node", "update-types": ["version-update:semver-major"] }] }
                 : {}),
+            ...(ecosystem === "github-actions" && pinnedWorkflows.length > 0 ? { ignore: pinnedWorkflows } : {}),
         }));
         return [yamlFile("deps", ".github/dependabot.yml", { version: 2, updates })];
     },
@@ -144,7 +193,7 @@ export const githubPlatform = {
             if (stack.ci) {
                 jobs.push(workflowKey("ci", path, ["jobs", stack.id], {
                     uses: workflowRef(ctx, stack.ci.workflow),
-                    with: stack.ci.with,
+                    with: stack.directory ? { ...stack.ci.with, "working-directory": stack.directory } : stack.ci.with,
                 }));
             }
         }
@@ -159,7 +208,13 @@ export const githubPlatform = {
         }
         if (jobs.length === 0)
             return [];
+        const called = [
+            ...ctx.stacks.flatMap((stack) => (stack.ci ? [stack.ci.workflow] : [])),
+            ...(ctx.config.modules.commits ? ["commitlint.yml"] : []),
+            ...(ctx.config.modules.drift ? ["repokeeper-check.yml"] : []),
+        ];
         return [
+            ...localWorkflows(ctx, "ci", called),
             workflowKey("ci", path, ["name"], "ci"),
             workflowKey("ci", path, ["on"], { pull_request: null, push: { branches: [defaultBranch(ctx.config)] } }),
             workflowKey("ci", path, ["permissions"], { contents: "read" }),
@@ -173,9 +228,11 @@ export const githubPlatform = {
             ...jobs,
         ];
     },
-    releaseAutomation(ctx, release) {
+    releaseAutomation(ctx, release, directory) {
         const path = ".github/workflows/release.yml";
         const seed = release.version ?? ctx.repo.releasedVersion ?? "0.0.0";
+        // release-please names a package by its folder; its changelog and extra files are relative to it
+        const packagePath = directory ?? ".";
         return [
             {
                 kind: "file",
@@ -184,7 +241,7 @@ export const githubPlatform = {
                 content: json({
                     $schema: RELEASE_PLEASE_SCHEMA,
                     packages: {
-                        ".": {
+                        [packagePath]: {
                             "release-type": release.type,
                             "changelog-path": "CHANGELOG.md",
                             "bump-minor-pre-major": true,
@@ -206,8 +263,9 @@ export const githubPlatform = {
                 kind: "seed",
                 module: "release",
                 path: ".release-please-manifest.json",
-                content: json({ ".": seed }),
+                content: json({ [packagePath]: seed }),
             },
+            ...localWorkflows(ctx, "release", ["release-please.yml"]),
             workflowKey("release", path, ["name"], "release"),
             workflowKey("release", path, ["on"], { push: { branches: [defaultBranch(ctx.config)] } }),
             workflowKey("release", path, ["permissions"], { contents: "read" }),

package/dist/platforms/gitlab.js

@@ -10,7 +10,7 @@ const md = (path, body) => ({
 /** Web address of the GitLab instance the repository lives on. */
 const baseUrl = (repo) => `https://${repo.host ?? "gitlab.com"}`;
 const CI_FILE = ".gitlab-ci.yml";
-const CI_KEYS = ["workflow", "node", "commits", "repokeeper", "renovate", "release"];
+const CI_KEYS = ["workflow", "node", "go", "commits", "repokeeper", "renovate", "release"];
 /** One managed top-level key of .gitlab-ci.yml; keys the user adds are left alone. */
 const ciKey = (module, key, value) => ({
     kind: "yaml",
@@ -48,6 +48,22 @@ function nodeJob(input) {
         ],
     };
 }
+/**
+ * The go stack's CI inputs as a GitLab job. No module cache: it would have to live inside the project
+ * folder, where `gofmt -l .` would read it as the project's own code.
+ */
+function goJob(input) {
+    // setup-go's "stable" is the image's `latest` tag
+    const versions = JSON.parse(input["go-versions"] ?? '["stable"]').map((version) => version === "stable" ? "latest" : version);
+    return {
+        stage: "test",
+        // biome-ignore lint/suspicious/noTemplateCurlyInString: a GitLab CI variable
+        image: "golang:${GO_VERSION}",
+        parallel: { matrix: [{ GO_VERSION: versions }] },
+        rules: [{ if: FOR_CHANGES }],
+        script: JSON.parse(input.commands ?? "[]"),
+    };
+}
 /** commitlint from a scratch directory, so the project needs no commitlint of its own. */
 const COMMITLINT = `dir="$(mktemp -d)"
 (cd "$dir" && echo '{ "private": true }' > package.json && npm install --no-audit --no-fund @commitlint/cli@${TOOL_VERSIONS.commitlintCli} @commitlint/config-conventional@${TOOL_VERSIONS.commitlintConventional})
@@ -75,7 +91,7 @@ const SEMANTIC_RELEASE = `dir="$(mktemp -d)"
 `;
 export const gitlabPlatform = {
     id: "gitlab",
-    stacks: ["node"],
+    stacks: ["node", "go"],
     changeRequest: "merge request",
     profileUrl: (repo) => (repo.owner ? `${baseUrl(repo)}/${repo.owner}` : null),
     securityReport: (repo) => repo.owner
@@ -137,6 +153,9 @@ export const gitlabPlatform = {
         const node = ctx.stacks.find((stack) => stack.id === "node")?.ci;
         if (node)
             jobs.push(ciKey("ci", "node", nodeJob(node.with)));
+        const go = ctx.stacks.find((stack) => stack.id === "go")?.ci;
+        if (go)
+            jobs.push(ciKey("ci", "go", goJob(go.with)));
         if (ctx.config.modules.commits) {
             jobs.push(ciKey("ci", "commits", {
                 stage: "test",
@@ -172,6 +191,8 @@ export const gitlabPlatform = {
     },
     releaseAutomation(ctx) {
         const branch = defaultBranch(ctx.config);
+        // a Go module's version is its tag: there is no file to bump, so the release is the changelog and the tag
+        const npm = ctx.stacks.some((stack) => stack.release.type === "node");
         return [
             {
                 kind: "file",
@@ -186,11 +207,11 @@ export const gitlabPlatform = {
                         ["@semantic-release/release-notes-generator", { preset: "conventionalcommits" }],
                         ["@semantic-release/changelog", { changelogFile: "CHANGELOG.md" }],
                         // bumps package.json and the npm lock file; publishing stays the project's own business
-                        ["@semantic-release/npm", { npmPublish: false }],
+                        ...(npm ? [["@semantic-release/npm", { npmPublish: false }]] : []),
                         [
                             "@semantic-release/git",
                             {
-                                assets: ["CHANGELOG.md", "package.json", "package-lock.json", "npm-shrinkwrap.json"],
+                                assets: ["CHANGELOG.md", ...(npm ? ["package.json", "package-lock.json", "npm-shrinkwrap.json"] : [])],
                                 // biome-ignore lint/suspicious/noTemplateCurlyInString: a semantic-release template
                                 message: "chore(release): ${nextRelease.version} [skip ci]",
                             },

package/dist/stacks/index.js

@@ -1,3 +1,5 @@
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
 import { STACK_IDS } from "../config/types.js";
 import { dartStack } from "./dart.js";
 import { dotnetStack } from "./dotnet.js";
@@ -34,3 +36,57 @@ export async function detectStacks(root) {
     // scripts beside another stack belong to that stack; the script pack is for script-only repositories
     return found.length > 1 ? found.filter((id) => id !== "script") : found;
 }
+/** Folders that hold a project's by-products or samples rather than a project of the repository. */
+const NOT_A_PROJECT = new Set([
+    "node_modules",
+    "vendor",
+    "dist",
+    "build",
+    "target",
+    "out",
+    "bin",
+    "obj",
+    "coverage",
+    "example",
+    "examples",
+    "test",
+    "tests",
+    "fixtures",
+    "doc",
+    "docs",
+]);
+/**
+ * The stacks of a repository and where they are: at the root or, when the root holds no project
+ * (a monorepo such as frontend/ and backend/), in its immediate folders.
+ */
+export async function detectStackLayout(root) {
+    const atRoot = await detectStacks(root);
+    const rooted = { stacks: atRoot, directories: {}, skipped: [] };
+    // loose scripts at the root do not make it a project: a monorepo often keeps some beside its folders
+    if (atRoot.some((id) => id !== "script"))
+        return rooted;
+    const directories = {};
+    const skipped = [];
+    const folders = readdirSync(root, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && !entry.name.startsWith(".") && !NOT_A_PROJECT.has(entry.name))
+        .map((entry) => entry.name)
+        .sort();
+    for (const folder of folders) {
+        for (const id of await detectStacks(join(root, folder))) {
+            if (directories[id] === undefined)
+                directories[id] = folder;
+            else
+                skipped.push({ stack: id, directory: folder });
+        }
+    }
+    let stacks = STACK_IDS.filter((id) => directories[id] !== undefined);
+    // nothing but scripts in the folders either: the root's own answer stands
+    if (atRoot.length > 0 && stacks.every((id) => id === "script"))
+        return rooted;
+    // as at the root: a folder of scripts beside real projects is tooling, not a stack
+    if (stacks.length > 1 && directories.script !== undefined) {
+        stacks = stacks.filter((id) => id !== "script");
+        delete directories.script;
+    }
+    return { stacks, directories, skipped: skipped.filter((entry) => stacks.includes(entry.stack)) };
+}

package/dist/stacks/support.js

@@ -10,6 +10,25 @@ export function checkKeys(stack, options, keys) {
         }
     }
 }
+/**
+ * The `directory` option every stack takes: the folder of a monorepo the stack lives in.
+ * Returns it with forward slashes and no trailing slash, or undefined for the repository root.
+ */
+export function stackDirectory(stack, options) {
+    const value = options.directory;
+    if (value === undefined)
+        return undefined;
+    const key = `${CONFIG_FILE}: stack_options.${stack}.directory`;
+    if (typeof value !== "string" || value.trim() === "")
+        throw new ConfigError(`${key} must be a folder name`);
+    const directory = value.trim().replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+    if (directory === "" || directory === ".")
+        return undefined;
+    if (directory.startsWith("/") || /^[A-Za-z]:/.test(directory) || directory.split("/").includes("..")) {
+        throw new ConfigError(`${key} must be a folder inside the repository, such as backend or apps/api`);
+    }
+    return directory;
+}
 /** A list option; YAML numbers such as `[22, 24]` count as strings. */
 export function stringList(stack, options, key) {
     const value = options[key];

package/dist/templates.js

@@ -1,6 +1,18 @@
-import { readFileSync } from "node:fs";
+import { readdirSync, readFileSync } from "node:fs";
 import { normalizeEol } from "./sync/hash.js";
 /** Reads a bundled template with LF endings; works from src/ (tests) and dist/ (package). */
 export function readTemplate(relativePath) {
     return normalizeEol(readFileSync(new URL(`../templates/${relativePath}`, import.meta.url), "utf8"));
 }
+/** File names of the reusable workflows generated CI and release files can call. */
+export const REUSABLE_WORKFLOW = /^(stack-[a-z]+|commitlint|release-please|repokeeper-check)\.yml$/;
+/** Reads one of the reusable workflows shipped with the package, with LF endings. */
+export function readWorkflow(file) {
+    return normalizeEol(readFileSync(new URL(`../.github/workflows/${file}`, import.meta.url), "utf8"));
+}
+/** Every reusable workflow shipped with the package, by file name. */
+export function listWorkflows() {
+    return readdirSync(new URL("../.github/workflows/", import.meta.url))
+        .filter((name) => REUSABLE_WORKFLOW.test(name))
+        .sort();
+}

package/dist/version.js

@@ -18,6 +18,8 @@ export const TOOL_VERSIONS = {
 export const REUSABLE_REPO = "vannt-dev/repokeeper";
 /** Moving tag callers pin to: the major version of this repokeeper (v0 during 0.x). */
 export const WORKFLOW_REF = `v${PACKAGE_VERSION.split(".")[0]}`;
+/** The tag of this release, for callers that pin to it instead of following the major tag. */
+export const EXACT_WORKFLOW_REF = `v${PACKAGE_VERSION}`;
 export function compareVersions(a, b) {
     const pa = a.split(".").map(Number);
     const pb = b.split(".").map(Number);