@bakers-build/addon-forge-github 0.0.0-stage → 0.8.1-next.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 keytec GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @bakers-build/addon-forge-github
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+bakers.build forge backend for GitHub: a GitHub App installation token scoped to one repository. Implements @bakers-build/addon-forge's ForgeBackend contract.
+
+Part of the bakers.build CLI. Install the meta package `@bakers-build/bakers` to get the `bakers` CLI with all addons. Source: https://github.com/bakers-build/bakers-build (bakers-cli/).

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+import { type ForgeBackendFactory } from '@bakers-build/addon-forge/backend';
+declare const factory: ForgeBackendFactory;
+export default factory;

package/dist/src/index.js

@@ -0,0 +1,196 @@
+// The GitHub forge backend: a GitHub App's installation token, minted with
+// an RS256 app JWT, scoped to the one configured repository and cached until
+// shortly before it expires; or, with `auth: 'gh'`, the conductor's own `gh`
+// login. The repository comes from config, never from a clone's `origin`.
+import { createSign } from 'node:crypto';
+import { cliToken, requestJson, } from '@bakers-build/addon-forge/backend';
+const API = 'https://api.github.com';
+const REFRESH_MS = 60_000;
+function settingsOf(raw) {
+    const s = (raw ?? {});
+    if (typeof s.repository !== 'string' ||
+        !/^[\w.-]+\/[\w.-]+$/.test(s.repository))
+        throw new Error("repository must be 'owner/repo'");
+    if (s.auth === 'gh')
+        return {
+            repository: s.repository,
+            gh: true,
+            appId: '',
+            installationId: '',
+            privateKey: '',
+        };
+    if (s.auth !== undefined)
+        throw new Error("auth must be 'gh' or left out for a GitHub App");
+    for (const k of ['app_id', 'installation_id'])
+        if (typeof s[k] !== 'number' && (typeof s[k] !== 'string' || s[k] === ''))
+            throw new Error(`${k} must be the App's numeric ${k.replace('_', ' ')}`);
+    const fromEnv = typeof s.private_key_env === 'string'
+        ? process.env[s.private_key_env]
+        : undefined;
+    const privateKey = typeof s.private_key === 'string' ? s.private_key : fromEnv;
+    if (!privateKey)
+        throw new Error('private_key or private_key_env (naming a set environment variable) must give the App private key');
+    return {
+        repository: s.repository,
+        gh: false,
+        appId: String(s.app_id),
+        installationId: String(s.installation_id),
+        privateKey,
+    };
+}
+const b64url = (v) => Buffer.from(v).toString('base64url');
+function appJwt(appId, key) {
+    const now = Math.floor(Date.now() / 1000);
+    const head = `${b64url(JSON.stringify({ alg: 'RS256', typ: 'JWT' }))}.${b64url(JSON.stringify({ iat: now - 60, exp: now + 540, iss: appId }))}`;
+    return `${head}.${createSign('RSA-SHA256').update(head).sign(key, 'base64url')}`;
+}
+const prOf = (p) => ({
+    number: p.number,
+    url: p.html_url,
+    head: p.head.ref,
+    base: p.base.ref,
+    title: p.title,
+    headSha: p.head.sha,
+});
+function runStatus(r) {
+    if (r.status !== 'completed')
+        return 'pending';
+    return ['success', 'neutral', 'skipped'].includes(r.conclusion ?? '')
+        ? 'success'
+        : 'failure';
+}
+function stateStatus(state) {
+    if (state === 'success')
+        return 'success';
+    return state === 'pending' ? 'pending' : 'failure';
+}
+const basic = (token) => Buffer.from(`x-access-token:${token}`).toString('base64');
+const factory = async (raw, context) => {
+    const s = settingsOf(raw);
+    const doFetch = context.fetch ?? fetch;
+    const [owner] = s.repository.split('/');
+    const repo = `${API}/repos/${s.repository}`;
+    let token;
+    // Every JWT and token ever minted: a value replaced by a refresh may still be echoed.
+    const minted = [];
+    const ghToken = cliToken('gh', ['auth', 'token', '--hostname', 'github.com'], minted);
+    const accessToken = async () => {
+        if (s.gh) {
+            const value = await ghToken();
+            if (!minted.includes(basic(value)))
+                minted.push(basic(value));
+            return value;
+        }
+        if (token && Date.now() < token.until)
+            return token.value;
+        const jwt = appJwt(s.appId, s.privateKey);
+        minted.push(jwt);
+        const out = (await requestJson(doFetch, `${API}/app/installations/${s.installationId}/access_tokens`, {
+            method: 'POST',
+            headers: {
+                authorization: `Bearer ${jwt}`,
+                accept: 'application/vnd.github+json',
+                'content-type': 'application/json',
+            },
+            body: JSON.stringify({ repositories: [s.repository.split('/')[1]] }),
+        }));
+        minted.push(out.token, basic(out.token));
+        token = {
+            value: out.token,
+            until: Date.parse(out.expires_at) - REFRESH_MS,
+        };
+        return out.token;
+    };
+    const api = async (path, init = {}) => requestJson(doFetch, `${repo}${path}`, {
+        method: init.method ?? 'GET',
+        headers: {
+            authorization: `Bearer ${await accessToken()}`,
+            accept: 'application/vnd.github+json',
+            'content-type': 'application/json',
+        },
+        ...(init.body === undefined ? {} : { body: JSON.stringify(init.body) }),
+        ...(init.allow404 ? { allow404: true } : {}),
+    });
+    const pull = async (n) => (await api(`/pulls/${n}`));
+    const backend = {
+        id: 'github',
+        secrets: () => [...(s.privateKey ? [s.privateKey] : []), ...minted],
+        gitAuth: async () => ({
+            url: `https://github.com/${s.repository}.git`,
+            header: `Authorization: Basic ${basic(await accessToken())}`,
+        }),
+        findOpenPr: async (head) => {
+            const list = (await api(`/pulls?state=open&head=${encodeURIComponent(`${owner}:${head}`)}`));
+            const found = list.find((p) => p.head.ref === head);
+            return found && prOf(found);
+        },
+        createPr: async ({ head, base, title, body }) => prOf((await api('/pulls', {
+            method: 'POST',
+            body: { head, base, title, body },
+        }))),
+        updatePr: async (pr, { title, body }) => prOf((await api(`/pulls/${pr.number}`, {
+            method: 'PATCH',
+            body: { title, body },
+        }))),
+        openPrsWithBase: async (base) => (await api(`/pulls?state=open&base=${encodeURIComponent(base)}&per_page=100`))
+            .filter((p) => p.base.ref === base)
+            .map(prOf),
+        checks: async (ref, base) => {
+            const at = encodeURIComponent(ref);
+            const b = encodeURIComponent(base);
+            const [runs, status, rules, branch] = await Promise.all([
+                api(`/commits/${at}/check-runs?per_page=100`),
+                api(`/commits/${at}/status`),
+                api(`/rules/branches/${b}`, { allow404: true }),
+                api(`/branches/${b}`, { allow404: true }),
+            ]);
+            const required = new Set([
+                ...(rules ?? [])
+                    .filter((r) => r.type === 'required_status_checks')
+                    .flatMap((r) => r.parameters?.required_status_checks ?? [])
+                    .map((c) => c.context),
+                ...(branch?.protection?.required_status_checks?.contexts ?? []),
+            ]);
+            const rows = [
+                ...runs.check_runs.map((r) => ({
+                    name: r.name,
+                    status: runStatus(r),
+                    required: required.has(r.name),
+                })),
+                ...status.statuses.map((st) => ({
+                    name: st.context,
+                    status: stateStatus(st.state),
+                    required: required.has(st.context),
+                })),
+            ];
+            for (const name of required)
+                if (!rows.some((r) => r.name === name))
+                    rows.push({ name, status: 'missing', required: true });
+            return rows;
+        },
+        mergeBlocker: async (pr) => {
+            const p = await pull(pr.number);
+            if (p.mergeable === null || p.mergeable === undefined)
+                return 'mergeability is not computed yet; call again shortly';
+            return p.mergeable ? undefined : 'merge conflict with its base';
+        },
+        merge: async (pr, o) => {
+            await api(`/pulls/${pr.number}/merge`, {
+                method: 'PUT',
+                body: {
+                    merge_method: o.method,
+                    commit_title: o.subject,
+                    commit_message: o.body,
+                    sha: pr.headSha,
+                },
+            });
+            if (o.deleteSource)
+                await api(`/git/refs/heads/${pr.head.split('/').map(encodeURIComponent).join('/')}`, {
+                    method: 'DELETE',
+                });
+        },
+        isMerged: async (pr) => (await pull(pr.number)).merged === true,
+    };
+    return backend;
+};
+export default factory;

package/options.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://bakers.build/schema/addon-forge-github/options.schema.json",
+  "title": "@bakers-build/addon-forge-github options",
+  "description": "The forge entry's with.backend.with: a GitHub App, or the conductor's gh login with auth 'gh'.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "repository"
+  ],
+  "properties": {
+    "repository": {
+      "type": "string",
+      "pattern": "^[\\w.-]+/[\\w.-]+$",
+      "description": "owner/repo."
+    },
+    "auth": {
+      "const": "gh",
+      "description": "Use the conductor's own gh login instead of a GitHub App."
+    },
+    "app_id": {
+      "type": [
+        "integer",
+        "string"
+      ],
+      "minLength": 1
+    },
+    "installation_id": {
+      "type": [
+        "integer",
+        "string"
+      ],
+      "minLength": 1
+    },
+    "private_key": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The App private key (PEM); machine config only."
+    },
+    "private_key_env": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Names the conductor environment variable that holds the credential."
+    }
+  },
+  "if": {
+    "required": [
+      "auth"
+    ]
+  },
+  "else": {
+    "required": [
+      "app_id",
+      "installation_id"
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@bakers-build/addon-forge-github",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.8.1-next.2",
+  "description": "bakers.build forge backend for GitHub: a GitHub App installation token scoped to one repository. Implements @bakers-build/addon-forge's ForgeBackend contract.",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": "./dist/src/index.js",
+    "./options.schema.json": "./options.schema.json"
+  },
+  "files": [
+    "dist/src",
+    "options.schema.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bakers-build/bakers-build.git",
+    "directory": "bakers-cli/addons/forge-github"
+  },
+  "peerDependencies": {
+    "@bakers-build/addon-forge": "^0.8.1-next.2",
+    "@bakers-build/core": "^0.8.1-next.2"
+  },
+  "bakersBuild": {
+    "commit": "0177880667693d1c36c65ffced82d2f3a17cbf2a",
+    "channel": "next"
+  }
+}