From 26c37024ae1096cbe1a3bc42607538c16c4a7106 Mon Sep 17 00:00:00 2001
From: unkin-agent <unkin-agent@unkin.net>
Date: Tue, 11 Aug 2026 23:54:34 +1000
Subject: [PATCH] ui: add deb and github_deb usage instructions (#113)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Why

The `deb` and `github_deb` repository types had no tailored "How do I use this?" snippets in the UI — they fell through to the generic default (curl-a-file-by-path), which does not tell a user how to actually wire the repo into apt. This adds real, end-to-end-validated apt instructions mirroring how the existing package types (rpm, npm, etc.) are handled.

## How

- Adds a `case 'deb':` to `buildSnippets` that branches on `isLocal`: a flat real apt repo served at `/api/v1/local/<name>/ ./` with `[trusted=yes]` plus a publish-a-.deb snippet for locals, and a caching-proxy `deb <proxy> <suite> <component>` form (upstream-signed, no `[trusted=yes]`) for remotes.
- Adds a `case 'github_deb':` emitting the metadata-only flat form `deb [trusted=yes] <proxy>/ ./`, whose index is synthesized from a GitHub repo's release .deb assets.
- Reuses the existing `url`/`proxy`/`isLocal` helpers and matches the surrounding case style; leaves the rpm and other cases untouched.

Reviewed-on: https://git.unkin.net/unkin/artifactapi/pulls/113
Co-authored-by: unkin-agent <unkin-agent@unkin.net>
Co-committed-by: unkin-agent <unkin-agent@unkin.net>
---
 ui/src/components/UsageInstructions.tsx | 41 +++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/ui/src/components/UsageInstructions.tsx b/ui/src/components/UsageInstructions.tsx
index 357dea4..1791ced 100644
--- a/ui/src/components/UsageInstructions.tsx
+++ b/ui/src/components/UsageInstructions.tsx
@@ -208,6 +208,47 @@ go mod download`,
         },
       ];
 
+    case 'deb':
+      return isLocal
+        ? [
+            {
+              title: 'Add the apt repo (real apt repo, flat — Packages/Release auto-generated)',
+              language: 'bash',
+              code: `echo 'deb [trusted=yes] ${url}/api/v1/local/${name}/ ./' | sudo tee /etc/apt/sources.list.d/${name}.list
+sudo apt-get update
+sudo apt-get install <package>`,
+              note: '[trusted=yes]: artifactapi serves the flat repo unsigned (matches the rpm repo\'s gpgcheck=0). The `./` is the flat-repo suite — apt fetches Packages/Release from the repo root.',
+            },
+            {
+              title: 'Publish a .deb (index regenerates automatically)',
+              language: 'bash',
+              code: `curl -fsSL --upload-file ./my-package_1.0_amd64.deb \\
+  ${url}/api/v2/remotes/${name}/files/my-package_1.0_amd64.deb`,
+            },
+          ]
+        : [
+            {
+              title: 'Add the apt repo (caching proxy)',
+              language: 'bash',
+              code: `echo 'deb ${proxy} <suite> <component>' | sudo tee /etc/apt/sources.list.d/${name}.list
+sudo apt-get update
+sudo apt-get install <package>`,
+              note: "Signatures are verified against the upstream mirror's real signed Release through the proxy (no [trusted=yes] needed). Example suite/component: bookworm main.",
+            },
+          ];
+
+    case 'github_deb':
+      return [
+        {
+          title: 'Add the apt repo (metadata-only, from GitHub releases)',
+          language: 'bash',
+          code: `echo 'deb [trusted=yes] ${proxy}/ ./' | sudo tee /etc/apt/sources.list.d/${name}.list
+sudo apt-get update
+sudo apt-get install <package>`,
+          note: "The apt index is synthesized from the configured GitHub repo's release .deb assets; package downloads are redirected to the backing releases remote. Served unsigned, so [trusted=yes].",
+        },
+      ];
+
     case 'generic':
     default:
       return [