@crossbind/extension-github 0.0.0-stage → 2.0.0-beta.69

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Buğra Sarı and crossbind contributors
+
+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,24 @@
-# Temporary Holding Version
+# @crossbind/extension-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.
+Puts a desktop app's installers and update on a GitHub release.
+
+An app has it by having `@crossbind/core-app-host`, which lists it as a dependency: there is nothing to install or list.
+
+## Use
+
+```sh
+npx crossbind app publish github -p macos
+```
+
+It builds the desktop app and puts its installers, and with `app.updater` its update and the update's manifest, on the
+GitHub release of the version `package.json` gives. `--draft` leaves the release a draft.
+
+## Platforms
+
+macOS, Linux and Windows apps.
+
+## Replace or leave out
+
+An extension named `github` with a publisher takes its place, and `app: { without: ['github'] }` in `crossbind.config.js` leaves it out. [extensions.md](https://github.com/crossbind/crossbind/blob/main/docs/api/extensions.md#publishers) says what one gives.
+
+[app.md](https://github.com/crossbind/crossbind/blob/main/docs/api/app.md#github-releases) has the token it takes and the address `app.updater.url` points at.

package/crossbind.extension.js

@@ -0,0 +1,135 @@
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import {
+    githubCaller, githubRepository, githubToken, newRelease, publishRelease, releaseOf, uploadAsset,
+} from './src/githubReleases.js';
+
+// The private key a build signs a desktop app's updates with, which it reads from the environment.
+const UPDATER_KEY = 'CROSSBIND_UPDATER_PRIVATE_KEY';
+// The installer whose files are an app's update.
+const UPDATE_INSTALLER = 'updater';
+const NO_REPOSITORY = 'crossbind: GitHub Releases takes the app to a repository of GitHub\'s, which neither CROSSBIND_GITHUB_REPOSITORY, GITHUB_REPOSITORY nor package.json\'s repository names: set repository to owner/name.';
+const NO_TOKEN = 'crossbind: GitHub takes a release from a token with write access to the repository\'s contents: set GH_TOKEN or GITHUB_TOKEN, as a workflow does with its own, or sign in with `gh auth login`.';
+const NO_UPDATE_KEY = `crossbind: app.updater has the app update from where it says, so its release takes the update ${UPDATER_KEY} signs: set it, as app.md's Updates says.`;
+
+const isSame = (one, other) => typeof one === 'string' && one.toLowerCase() === other.toLowerCase();
+const git = (api, args) => {
+    const result = spawnSync('git', args, { cwd: api.project.root, encoding: 'utf8' });
+    return result.status === 0 ? result.stdout.trim() : null;
+};
+const isPrerelease = (version) => version.split('+')[0].includes('-');
+
+// The commit a new release's tag is made at where the repository has no such tag yet: the one a workflow of that
+// repository runs for, else the project's own where its origin is that repository; else none, and GitHub makes it at its
+// default branch.
+function releaseCommit(api, repository) {
+    if (process.env.GITHUB_SHA) return isSame(process.env.GITHUB_REPOSITORY, repository) ? process.env.GITHUB_SHA : null;
+    const origin = git(api, ['remote', 'get-url', 'origin']);
+    return origin && isSame(githubRepository({ repository: origin }, {}), repository) ? git(api, ['rev-parse', 'HEAD']) : null;
+}
+
+// A macOS app's file takes the platform and arch into its name after the app's, as one release holds both arches', unless
+// it has them already, as an update's, whose manifest names it.
+function macosName(api, app, arch, file) {
+    const stem = path.basename(app, '.app');
+    const name = path.basename(file);
+    const own = `${api.project.name}-darwin-${arch}`;
+    if (name.startsWith(`${own}.`) || name.startsWith(`${own}-`)) return name;
+    const rest = name.startsWith(`${stem}.`) || name.startsWith(`${stem}-`) ? name.slice(stem.length) : `-${name}`;
+    return `${api.project.name}-darwin-${arch}${rest}`;
+}
+
+// The files of an app's release, under the names the release gives them: what each of its installers made, among them
+// with app.updater the update's. A Linux or Windows app's update is one of its installers' files, which goes up once.
+function releaseFiles(api, { app, arch, installers }, hasUpdate) {
+    if (!installers.some(({ name }) => name !== UPDATE_INSTALLER)) throw new Error(`crossbind: the build made no installer of ${app}, so nothing went to GitHub Releases.`);
+    if (hasUpdate && !installers.some(({ name }) => name === UPDATE_INSTALLER)) {
+        throw new Error(`crossbind: the build made no update of ${app}, which app.updater takes, so nothing went to GitHub Releases.`);
+    }
+    const files = [...new Set(installers.flatMap(({ files: made }) => made.map((file) => path.resolve(file))))];
+    return files.map((file) => ({ file, name: api.platform === 'macos' ? macosName(api, app, arch, file) : path.basename(file) }));
+}
+
+// What an app updates from the release misses: its manifest at the address of the newest release's, a version that
+// release can be, and an address it can fetch with no token.
+async function warnUpdates(api, call, repository, updater) {
+    const latest = `https://github.com/${repository}/releases/latest/download/${api.project.name}-{platform}-{arch}.update.json`;
+    if (!isSame(updater.url, latest)) {
+        api.warn(`crossbind: app.updater.url is ${updater.url}, not ${latest}, so the app does not update from the newest of ${repository}'s releases.`);
+        return;
+    }
+    if (isPrerelease(api.app.version)) api.warn(`crossbind: ${api.app.version} is a prerelease, which GitHub never makes the latest release, so no app updates to it.`);
+    if ((await call('GET', '')).private) api.warn(`crossbind: ${repository} is private, whose releases GitHub gives no app without a token, so none updates from them.`);
+}
+
+// The publisher of a desktop app's installers, and its update with app.updater, to a GitHub release of its version, as
+// its tag v<version> names it: a release made or taken as it is, where an asset of the same name gives way. It puts out
+// the release's page and each file's address, for a publisher after it.
+export default function github() {
+    return {
+        name: 'github',
+        contract: 1,
+        root: import.meta.dirname,
+        publisher: {
+            platform: 'desktop',
+            store: 'GitHub Releases',
+            options: {
+                draft: { help: "leave the release a draft, which a publish without --draft, or GitHub's page, puts out" },
+            },
+
+            async check(api) {
+                const missing = [];
+                const repository = githubRepository(api.project.package);
+                if (!repository) missing.push(NO_REPOSITORY);
+                const token = githubToken();
+                if (!token) missing.push(NO_TOKEN);
+                const { updater } = api.config.app;
+                if (updater && !process.env[UPDATER_KEY]) missing.push(NO_UPDATE_KEY);
+                if (missing.length > 0) return { missing };
+                const { version } = api.app;
+                const call = githubCaller(repository, token);
+                if (updater) await warnUpdates(api, call, repository, updater);
+                const release = await releaseOf(call, `v${version}`);
+                const kind = release ? `${release.draft ? 'draft ' : ''}release` : 'new release';
+                api.log(`crossbind: publishing the ${api.platform} app of ${version} to ${repository}'s ${kind} v${version}; building the app first.`);
+                return { session: { call, repository, hasUpdate: Boolean(updater) } };
+            },
+
+            // The token writes to the repository, which the build has no need of.
+            buildEnv: () => ({ GH_TOKEN: undefined, GITHUB_TOKEN: undefined }),
+
+            async upload(api, { call, repository, hasUpdate }, { apps }) {
+                const { platform, app: { version }, options: { draft: isDraft } } = api;
+                const files = apps.flatMap((app) => releaseFiles(api, app, hasUpdate));
+                const twice = files.find(({ name }, index) => files.findIndex((other) => other.name === name) !== index);
+                if (twice) {
+                    const both = files.filter(({ name }) => name === twice.name).map(({ file }) => file);
+                    throw new Error(`crossbind: ${both.join(' and ')} would both be ${twice.name}, of which a GitHub release holds one, so nothing went to GitHub Releases.`);
+                }
+                const tag = `v${version}`;
+                // Another publish of the version may have made its release during this one's build.
+                let release = await releaseOf(call, tag);
+                if (!release) {
+                    const commit = releaseCommit(api, repository);
+                    if (!commit) api.log(`crossbind: ${repository} gets the tag ${tag} where it has none at its default branch, as it has no commit of this build's.`);
+                    release = await newRelease(call, { tag, commit, isPrerelease: isPrerelease(version) });
+                }
+                const uploaded = [];
+                for (const { file, name } of files) {
+                    api.log(`crossbind: uploading ${name} to ${tag}.`);
+                    uploaded.push(await uploadAsset(call, release, file, name));
+                }
+                const published = (out) => ({
+                    published: { repository, tag, url: out.html_url, files: uploaded.map(({ name, browser_download_url: url }) => ({ name, url })) },
+                });
+                if (release.draft && isDraft) {
+                    api.log(`crossbind: the ${platform} app of ${version} is on the draft release ${tag}, which a publish without --draft, or GitHub's page, puts out: ${release.html_url}`);
+                    return published(release);
+                }
+                const out = release.draft ? await publishRelease(call, release) : release;
+                api.log(`crossbind: the ${platform} app of ${version} is out on GitHub's release ${tag}${isDraft ? ', which was out already' : ''}: ${out.html_url}`);
+                return published(out);
+            },
+        },
+    };
+}

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@crossbind/extension-github",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "2.0.0-beta.69",
+  "description": "crossbind app extension: puts a desktop app's installers and update on a GitHub release.",
+  "homepage": "https://github.com/crossbind/crossbind/tree/main/extensions/github#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/crossbind/crossbind.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    "./crossbind.extension.js": "./crossbind.extension.js"
+  },
+  "files": [
+    "crossbind.extension.js",
+    "src"
+  ],
+  "crossbind": {
+    "extension": "./crossbind.extension.js"
+  },
+  "keywords": [
+    "crossbind-extension",
+    "crossbind",
+    "publishing",
+    "github",
+    "publisher",
+    "app"
+  ]
 }

package/src/githubReleases.js

@@ -0,0 +1,135 @@
+import fs from 'node:fs';
+import { spawnSync } from 'node:child_process';
+
+// A repository as GitHub names it, owner/name.
+const REPOSITORY = /^[\w.-]+\/[\w.-]+$/;
+// package.json's repository where it is GitHub's: owner/name or github:owner/name, as npm takes them, or its address,
+// git@github.com:owner/name.git as well.
+const GITHUB_ADDRESS = /^(?:(?:git\+)?(?:https?|ssh|git):\/\/(?:git@)?github\.com[/:]|git@github\.com:)([\w.-]+\/[\w.-]+?)(?:\.git)?\/?$/;
+
+// The token GitHub takes a release from: GH_TOKEN or GITHUB_TOKEN, as GitHub's CLI and Actions name it, else the GitHub
+// CLI's own sign-in where it has one; null without any.
+export function githubToken(env = process.env) {
+    const token = env.GH_TOKEN || env.GITHUB_TOKEN;
+    if (token) return token;
+    const signedIn = spawnSync('gh', ['auth', 'token'], { encoding: 'utf8' });
+    return signedIn.status === 0 && signedIn.stdout.trim() ? signedIn.stdout.trim() : null;
+}
+
+// The repository a release goes to: CROSSBIND_GITHUB_REPOSITORY, else GITHUB_REPOSITORY, as GitHub Actions sets it,
+// else package.json's repository where it is GitHub's; null without one.
+export function githubRepository(packageJson, env = process.env) {
+    const variable = ['CROSSBIND_GITHUB_REPOSITORY', 'GITHUB_REPOSITORY'].find((name) => env[name]);
+    if (variable) {
+        if (!REPOSITORY.test(env[variable])) throw new Error(`crossbind: ${variable} ${JSON.stringify(env[variable])} names no repository, as owner/name does.`);
+        return env[variable];
+    }
+    const given = typeof packageJson?.repository === 'string' ? packageJson.repository : packageJson?.repository?.url;
+    if (typeof given !== 'string') return null;
+    const address = GITHUB_ADDRESS.exec(given)?.[1];
+    if (address) return address;
+    const short = given.replace(/^github:/, '');
+    return REPOSITORY.test(short) ? short : null;
+}
+
+const apiAddress = () => process.env.GITHUB_API_URL || 'https://api.github.com';
+
+// What GitHub said of a call it refused, with the field of each error where it names no message, as a 422's do.
+const saidIn = (body) => [body?.message, ...(body?.errors ?? []).map((error) => error.message ?? [error.resource, error.field, error.code].filter(Boolean).join(' '))]
+    .filter(Boolean).join(': ');
+
+function githubError(status, body, method, route, repository) {
+    const said = saidIn(body);
+    let text = `crossbind: GitHub answered ${method} ${route} with ${status}${said ? `: ${said}` : '.'}`;
+    if (status === 401) {
+        text = "crossbind: GitHub refused the token: it has expired, or is none of GitHub's; GH_TOKEN or GITHUB_TOKEN names it, else `gh auth login` signs in.";
+    } else if (status === 404 && route === `/repos/${repository}`) {
+        text = `crossbind: GitHub has no repository ${repository} the token sees: check its name, and that the token reaches it.`;
+    } else if ((status === 403 && !/rate limit/i.test(said)) || (status === 404 && route.endsWith('/releases'))) {
+        text += `\ncrossbind: the token takes write access to the contents of ${repository}: a workflow gives its GITHUB_TOKEN \`permissions: contents: write\`, a fine-grained token "Contents" read and write, a classic one the repo scope.`;
+    }
+    return Object.assign(new Error(text), { status, body });
+}
+
+// A caller of GitHub's API for one repository, at a route of the repository's or at an address GitHub gave, as an
+// upload's. A file's bytes go up as they are.
+export function githubCaller(repository, token) {
+    return async (method, route, body) => {
+        const isAddress = route.startsWith('https://');
+        const address = isAddress ? route : `${apiAddress()}/repos/${repository}${route}`;
+        const isBytes = Buffer.isBuffer(body);
+        const response = await fetch(address, {
+            method,
+            headers: {
+                authorization: `Bearer ${token}`,
+                accept: 'application/vnd.github+json',
+                'x-github-api-version': '2022-11-28',
+                'user-agent': 'crossbind',
+                ...(body === undefined ? {} : { 'content-type': isBytes ? 'application/octet-stream' : 'application/json' }),
+            },
+            body: isBytes || body === undefined ? body : JSON.stringify(body),
+        });
+        const shown = isAddress ? new URL(route).pathname : `/repos/${repository}${route.split('?')[0]}`;
+        const text = await response.text();
+        let json = null;
+        try {
+            json = text ? JSON.parse(text) : {};
+        } catch {
+            if (response.ok) throw new Error(`crossbind: GitHub answered ${method} ${shown} with no JSON, as a proxy between might: ${text.slice(0, 200)}`);
+        }
+        if (response.ok) return json;
+        throw githubError(response.status, json, method, shown, repository);
+    };
+}
+
+// The oldest draft of a tag on the first page of the repository's releases, which lists the newest first; drafts have no
+// tag yet, which GitHub's lookup by tag goes by.
+async function draftOf(call, tag) {
+    const drafts = (await call('GET', '/releases?per_page=100')).filter((release) => release.draft && release.tag_name === tag);
+    return drafts.reduce((oldest, release) => (oldest && oldest.id < release.id ? oldest : release), null);
+}
+
+// The release of a tag: the one GitHub has out, else its oldest draft; null without one.
+export async function releaseOf(call, tag) {
+    const published = await call('GET', `/releases/tags/${encodeURIComponent(tag)}`).catch((error) => {
+        if (error.status === 404) return null;
+        throw error;
+    });
+    return published ?? draftOf(call, tag);
+}
+
+// A new draft release of a tag, at the commit given or else the default branch's, with the notes GitHub writes of the
+// changes since the last. Publishes of the same version at once, as a matrix's jobs, each make one: all then take the
+// oldest, and the others go. A tag GitHub has a release of out takes that one.
+export async function newRelease(call, { tag, commit, isPrerelease }) {
+    let made;
+    try {
+        made = await call('POST', '/releases', {
+            tag_name: tag, ...(commit ? { target_commitish: commit } : {}), name: tag, draft: true, prerelease: isPrerelease, generate_release_notes: true,
+        });
+    } catch (error) {
+        const out = error.status === 422 && (error.body?.errors ?? []).some(({ code }) => code === 'already_exists') ? await releaseOf(call, tag) : null;
+        if (!out) throw error;
+        return out;
+    }
+    const oldest = await draftOf(call, tag) ?? made;
+    if (oldest.id !== made.id) await call('DELETE', `/releases/${made.id}`);
+    return oldest;
+}
+
+// Uploads a file to a release under a name, in place of an asset of that name the release has, as an earlier publish of
+// the same version left, and returns the asset. GitHub renames a name with characters it takes none of, which the
+// update's manifest would no longer find, so that stops the publish.
+export async function uploadAsset(call, release, file, name) {
+    const bytes = fs.readFileSync(file);
+    const old = (release.assets ?? []).find((asset) => asset.name === name);
+    if (old) await call('DELETE', `/releases/assets/${old.id}`);
+    const uploaded = await call('POST', `${release.upload_url.replace(/\{.*\}$/, '')}?name=${encodeURIComponent(name)}`, bytes);
+    if (uploaded.name !== name) {
+        throw new Error(`crossbind: GitHub named ${name} ${uploaded.name}, as it takes no such name: the file's name takes letters, digits, . _ and - alone, as general.name in crossbind.config.js does for crossbind's own installers.`);
+    }
+    return uploaded;
+}
+
+// Puts a draft out, latest unless GitHub has a newer version out, so a fix of an older line leaves the newest latest.
+export const publishRelease = (call, release) => call('PATCH', `/releases/${release.id}`, { draft: false, make_latest: 'legacy' });