Merge pull request #5 from keturn/feat/assemble

Author: keturn

.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+    "cSpell.words": [
+        "dearmor",
+        "Tauri"
+    ]
+}

README.md

@@ -0,0 +1,82 @@
+# Debian Repositories (apt support) for GitHub Releases
+
+It's great when GitHub-hosted projects produce `.deb` packages in their release workflow[^1],
+but GitHub has never bothered to make a GitHub project something you can add to your system's `sources.list` to get ongoing updates.
+
+Here we aim to make it easy and affordable to make an apt-compatible repository for your releases.
+
+[^1]: Shoutout to [GoReleaser](https://goreleaser.com/) and [Tauri](https://v2.tauri.app/distribute/debian/) as a few tools I've seen enabling Debian packaging in the wild.
+
+
+## Requirements
+
+```sh
+sudo apt-get install --no-recommends dpkg-dev sq xz-utils
+```
+
+And [Node.js v24 (LTS)](https://nodejs.org/en/download) with pnpm.
+
+
+## Usage
+
+### Importing a Release
+
+Import packages from your latest release:
+
+`gh-release-apt import owner/repo`
+
+If you want your repository to retain multiple versions,
+do save the resulting `pool/**/Packages` files (to version control or a persistent filesystem) so this release's packages don't have to be downloaded again next time.
+
+
+### Building the Repository
+
+With your signing key in the `SIGNING_KEY` environment variable, run:
+
+`gh-release-apt assemble`
+
+Then deploy to your server—_excluding_ the `.deb` files themselves.
+
+
+
+## Design
+
+The key feature we rely on is that apt will follow redirects.
+This means we *can* keep using standard GitHub Release asset hosting for the packages themselves—
+which is great, because we don't want the overhead of storing extra copies of them,
+GitHub keeps paying for the bandwidth,
+and the project's download analytics keep working.
+
+[GitHub Pages doesn't offer a way to configure redirects](https://github.com/orgs/community/discussions/86095),
+but other hosts do offer this in their static web hosting features.[^2]
+There is, however, often a limit on the number of redirect rules.
+For that reason, we organize the repository's package pool so it's easy to map back to GitHub URLs with a single rule (instead of Debian's alphabetized structure).
+
+[^2]: including [GitLab Pages](https://docs.gitlab.com/user/project/pages/redirects/), 
+[CloudFlare Workers Static Assets](https://developers.cloudflare.com/workers/static-assets/redirects/), 
+[AWS S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/how-to-page-redirect.html) or 
+[AWS Amplify](https://docs.aws.amazon.com/amplify/latest/userguide/redirects.html), 
+[NearlyFreeSpeech](https://faq.nearlyfreespeech.net/full/htaccess#htaccess), 
+[Firebase](https://firebase.google.com/docs/hosting/full-config#redirects),
+[Netlify](https://docs.netlify.com/manage/routing/redirects/overview/),
+[Vercel](https://vercel.com/docs/redirects/configuration-redirects),
+[Digital Ocean](https://docs.digitalocean.com/products/app-platform/how-to/url-rewrites/#configure-a-redirect),
+[Render](https://render.com/docs/redirects-rewrites),
+[pico.sh](https://pico.sh/pgs#-redirects),
+[Codeberg](https://docs.codeberg.org/codeberg-pages/redirects/),
+etc.
+
+
+## Appendix: Creating a Signing Key
+
+This is not the only way to create a signing key, but if you don't have one already,
+this creates a minimal key for signing only.
+
+```sh
+sq key generate --without-password --can-sign --cannot-encrypt --cannot-authenticate --shared-key --no-userids
+sq cert export --cert $FINGERPRINT | sq packet dearmor --output archive-keyring.pgp
+sq key export --cert $FINGERPRINT | gh secret set SIGNING_KEY
+```
+
+See [DebianRepository/UseThirdParty](https://wiki.debian.org/DebianRepository/UseThirdParty#OpenPGP_certificate_distribution)
+for recommendations on where to name and place the certificate.

integrations/cloudflare/templates/.gitignore

@@ -0,0 +1,178 @@
+# Debian Repository
+## deb package files are served by redirects
+*.deb
+## Packages in dist/ are generated (from those in pool/)
+/public/dist/**/Packages
+## Release files are auto-generated
+Release
+Release.gpg
+InRelease
+
+
+# Logs
+
+logs
+_.log
+npm-debug.log_
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.pnpm-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+
+report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
+
+# Runtime data
+
+pids
+_.pid
+_.seed
+\*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+
+lib-cov
+
+# Coverage directory used by tools like istanbul
+
+coverage
+\*.lcov
+
+# nyc test coverage
+
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+
+bower_components
+
+# node-waf configuration
+
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+
+build/Release
+
+# Dependency directories
+
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+
+web_modules/
+
+# TypeScript cache
+
+\*.tsbuildinfo
+
+# Optional npm cache directory
+
+.npm
+
+# Optional eslint cache
+
+.eslintcache
+
+# Optional stylelint cache
+
+.stylelintcache
+
+# Microbundle cache
+
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+
+.node_repl_history
+
+# Output of 'npm pack'
+
+\*.tgz
+
+# Yarn Integrity file
+
+.yarn-integrity
+
+# parcel-bundler cache (https://parceljs.org/)
+
+.cache
+.parcel-cache
+
+# Next.js build output
+
+.next
+out
+
+# Nuxt.js build / generate output
+
+.nuxt
+dist
+
+# Gatsby files
+
+.cache/
+
+# Comment in the public line in if your project uses Gatsby and not Next.js
+
+# https://nextjs.org/blog/next-9-1#public-directory-support
+
+# public
+
+# vuepress build output
+
+.vuepress/dist
+
+# vuepress v2.x temp and cache directory
+
+.temp
+.cache
+
+# Docusaurus cache and generated files
+
+.docusaurus
+
+# Serverless directories
+
+.serverless/
+
+# FuseBox cache
+
+.fusebox/
+
+# DynamoDB Local files
+
+.dynamodb/
+
+# TernJS port file
+
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+
+.vscode-test
+
+# yarn v2
+
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.yarn/install-state.gz
+.pnp.\*
+
+# wrangler project
+
+.dev.vars*
+!.dev.vars.example
+.env*
+!.env.example
+.wrangler/

integrations/cloudflare/templates/package.json

@@ -0,0 +1,13 @@
+{
+	"name": "<PACKAGE_NAME>",
+	"version": "0.0.0",
+	"private": true,
+	"scripts": {
+		"deploy": "wrangler deploy",
+		"dev": "wrangler dev",
+		"start": "wrangler dev"
+	},
+	"devDependencies": {
+		"wrangler": "^3.78.5"
+	}
+}

integrations/cloudflare/templates/public/.assetsignore

@@ -0,0 +1,2 @@
+# deb package files are served by redirects
+*.deb

integrations/cloudflare/templates/public/_redirects

@@ -0,0 +1 @@
+/pool/:owner/:repo/:tag/* https://www.github.com/:owner/:repo/releases/download/:tag/:splat

integrations/cloudflare/templates/public/index.html

@@ -0,0 +1,10 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<title>Debian Package Repository</title>
+	</head>
+	<body>
+		<p>FIXME: We should probably put something here about how to add this to your apt sources.list.</p>
+	</body>
+</html>

integrations/cloudflare/templates/wrangler.jsonc

@@ -0,0 +1,11 @@
+{
+  "name": "<WORKER_NAME>",
+  "compatibility_date": "<COMPATIBILITY_DATE>",
+  "assets": {
+    // The path to the directory containing the `index.html` file to be served at `/`
+    "directory": "./public"
+  },
+  "observability": {
+    "enabled": true
+  }
+}

package.json

@@ -19,6 +19,7 @@
   "dependencies": {
     "@octokit/rest": "^21.0.2",
     "commander": "^12.1.0",
+    "fdir": "^6.5.0",
     "fs-extra": "^11.2.0",
     "zx": "8.8.5-lite"
   },